Skip to main content
Once you’ve created a request, there are two ways to read it back:
  • GET /v1/requests/{requestId} — fetch one request
  • GET /v1/requests — list requests, filtered by date range or batch
Both return the same per-request RequestResponse shape, except the list endpoint omits four enrichment fields that can be large — see Concepts → Single-request vs list response shapes.

​
Single request

Fetch a specific request by its requestId: 
curl -H "Authorization: Bearer <token>" \
  https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/requests/8bF7xK2mP9qR4sT6uV0w
Read-after-write lag: for a few seconds after a successful POST /v1/requests, a GET /v1/requests/{requestId} for the just-created ID can return 404 REQUEST_NOT_FOUND even though the POST succeeded. If you poll, tolerate 404s for the first few seconds after create. The webhook flow sidesteps this entirely — by the time the webhook fires, the request is readable.

​
Response

{
  "requestId": "8bF7xK2mP9qR4sT6uV0w",
  "requestBatchId": "pH9kJ2lM4nB6vC8xZ7Qr",
  "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
  "requestType": "claim-status",
  "state": "SUCCESS",
  "inputs": {
    "payerName": "Sample Insurance Co",
    "memberId": "TEST123456789",
    "phoneNumber": "2125551234",
    "providerNpi": "1234567890",
    "dateOfService": "2026-03-15"
  },
  "results": {
    "claimStatus": "PAID",
    "paidAmount": "150.00",
    "checkNumber": "CHK998877",
    "paidDate": "2026-04-10"
  },
  "missingFields": [],
  "dateCreated": "2026-04-24T15:30:00.123456+00:00",
  "completedAt": "2026-04-24T15:32:18.987654+00:00",
  "dueDate": "2026-04-25T23:00:00+00:00",
  "internalId": "claim_internal_456",
  "internalTag": "march-batch",
  "modality": "phone_only",
  "data_completeness": null,
  "error": null,
  "payerLookup": {
    "inputPayerName": "Sample Insurance Co",
    "matchedPayerName": "Sample Insurance Company, Inc."
  },
  "to": "+12125551234",
  "callDuration": "00:08:42",
  "callSummary": "Verified claim status as PAID. Check #CHK998877 issued on 2026-04-10 for $150.00."
}
The shape of results is schema-specific — keys correspond to the fields defined by the request’s schema. Phone-call enrichment fields (transcript, recordingDownloadUrl, callDuration, callSummary, etc.) appear only when the request was fulfilled by a representative phone call. to echoes the dialed number only when you supplied it in inputs.phoneNumber; when the number came from payer-phone resolution, to is omitted and the matched payer is surfaced via payerLookup (without a phone number). The payerLookup block (inputPayerName / matchedPayerName) is present whenever a payer name was supplied or matched, mirroring the create response; it’s absent when no payer name applies. Requests fulfilled by more than one representative phone call also carry a contributingCalls array on the single-request read (GET /v1/requests/{requestId}), breaking out each call’s transcript, recording, and captured results. See the API Reference for the complete field list.

​
Errors

All non-2xx responses use the uniform {error, message, [details]} envelope.
HTTP codeerror codeMeaning
200—Request found
401(gateway envelope)Missing or invalid bearer token
404REQUEST_NOT_FOUNDThe request ID doesn’t exist for your account
404ACCOUNT_NOT_FOUNDThe API key resolves to an account that no longer exists. Contact support.
500INTERNAL_ERRORUnexpected server failure

​
Listing requests

GET /v1/requests returns multiple requests, filtered by query parameters: 
curl -H "Authorization: Bearer <token>" \
  "https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/requests?dateFrom=2026-04-20&dateTo=2026-04-25"
The parameters and their defaults are described in the table below; see the API Reference for GET /v1/requests for the full request schema and per-language code samples.

​
Response

{
  "requests": [
    {
      "requestId": "8bF7xK2mP9qR4sT6uV0w",
      "requestBatchId": "pH9kJ2lM4nB6vC8xZ7Qr",
      "state": "SUCCESS",
      "results": { "claimStatus": "PAID", "paidAmount": "150.00" },
      "modality": "phone_only",
      "error": null,
      ...
    },
    {
      "requestId": "aC3hN5jD8eL1fM2gK6Yo",
      "requestBatchId": "pH9kJ2lM4nB6vC8xZ7Qr",
      "state": "PROCESSING",
      "results": {},
      "modality": null,
      "error": null,
      ...
    }
  ]
}
Each entry follows the RequestResponse schema. Sorted by dateCreated descending (most recent first).
The list endpoint omits transcript, transcriptPostCall, and recordingDownloadUrl. When you need any of these, fetch the single-request endpoint with the requestId from the list. See Concepts → Single-request vs list response shapes for the full breakdown.

​
Query parameters

ParameterFormatDefaultNotes
dateFromYYYY-MM-DDToday, midnightInclusive
dateToYYYY-MM-DDTomorrow, midnightExclusive
requestBatchIdstring—Bypasses the date defaults — return all requests in the batch regardless of when they were created
When requestBatchId is provided, dateFrom and dateTo are ignored. When requestBatchId is not provided, dateFrom and dateTo default to today’s window.

​
By batch

Pass requestBatchId as a query parameter to fetch every request under a given batch, regardless of their individual state — useful for tracking progress. 
def batch_progress(token, batch_id):
    r = requests.get(
        f"https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/requests",
        params={"requestBatchId": batch_id},
        headers={"Authorization": f"Bearer {token}"},
    )
    items = r.json()["requests"]
    by_state = {}
    for item in items:
        by_state.setdefault(item["state"], 0)
        by_state[item["state"]] += 1
    return by_state
# {"SUCCESS": 4, "PARTIAL": 1, "FAILURE": 1, "PROCESSING": 2}
If your original POST /v1/requests batch was split across multiple requestBatchId values (see Creating a Request → Batch), iterate the unique requestBatchIds found in the create response and call this once per ID.

​
Errors

All non-2xx responses use the uniform {error, message, [details]} envelope.
HTTP codeerror codeMeaning
200—List returned (may be empty)
400INVALID_REQUESTdateFrom or dateTo wasn’t a valid YYYY-MM-DD date
401(gateway envelope)Missing or invalid bearer token
404ACCOUNT_NOT_FOUNDThe API key resolves to an account that no longer exists. Contact support.
500INTERNAL_ERRORUnexpected server failure

​
Reading after a webhook

The recommended end-to-end pattern is:
  1. Create a request with internalId so you can correlate.
  2. Receive the webhook when the request reaches a terminal state.
  3. Call GET /v1/requests/{requestId} to fetch the full result.
The webhook payload is intentionally compact (requestId, requestBatchId, state, optional internalId/internalTag). It tells you that the request is done; the GET fetches the actual results, missingFields, modality, and the error object on PARTIAL / FAILURE.