GET /v1/requests/{requestId}: fetch one requestGET /v1/requests: list requests, filtered by date range or batch
RequestResponse shape, except the list endpoint omits several enrichment fields that can be large. See Concepts → Single-request vs list response shapes.
Single request
Fetch a specific request by itsrequestId:
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
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 phone call, and always describe the request’s first call (its last attempt, if that call itself needed more than one try). If a later, separate call also contributed to the request (see below), these top-level fields don’t reflect it. to echoes the number that was actually dialed once a phone call has completed, whether you supplied it or SuperDial resolved it. The payerLookup block mirrors the create response: a six-field object (inputPayerName, inputPhoneNumber, matchedPayerName, matchedPayerPhone, phoneNumberToUse, phoneNumberSource) returned whenever payer phone number lookup is enabled for your account. phoneNumberToUse / phoneNumberSource report the number dialed and its origin; the matched* fields are populated only when SuperDial dialed its own matched number (otherwise null, with phoneNumberSource: "input"). Requests fulfilled by a phone call also carry a callSteps summary on the single-request read (GET /v1/requests/{requestId}), and a successful or partial one adds a contributingCalls breakdown and a resultSources map. See Calls behind a request below for the full, per-call view. See the API Reference for the complete field list.
Calls behind a request
A request usually completes in a single phone call, but it can take more than one. Every call rolls up into the one request: the merged answers land in the top-levelresults, and state reflects the request as a whole. When more than one call is involved, the single top-level transcript / callDuration / callSummary / recordingDownloadUrl fields still only describe the first call (see above). The three fields below are how you see every call that contributed:
callSteps: the steps, one entry per step. A step is a distinct calling effort, usually one schema (for example, verifying benefits, then checking prior authorization). Each step names the schema it ran viaschemaId(plus a human-readablename) and reports its ownstateand how many required fields it captured (fieldsCapturedoffieldsRequired, with anymissingFields). A simple request has one step; the same schema can appear in more than one step; they’ll shareschemaIdbut each still gets its own uniquekey. A single step can involve more than one call (a redial).numContributingCallssays how many. A step opened off an earlier one carriestriggeredBy(the earlier step’skey); the request’s first step hastriggeredBy: null. This is the summary: what was gathered, and which schema gathered it.contributingCalls: the individual phone calls behind those steps, one entry per call. Each has an opaqueiduniquely identifying that call, handy for your own logging, or for referencing a specific call in a support request, but not something you can parse or decode. Alongside it, each entry carries that call’s own transcript, recording, duration, summary, and captured fields, acallsequence number (1,2, …, in the order calls were placed), and acallSteplinking it to its step incallSteps. Because a step can involve more than one call, there can be more entries here than incallSteps. A call also carriestowhen it dialed a different number than the request’s original call. This is the detail: how it was gathered, call by call.resultSources: the map between them. For each field inresultsthat came from a phone call, it gives thecallnumber that produced it, so you can trace any answer all the way back: thecallnumber identifies the exactcontributingCallsentry, itscallStepnames the exact step incallSteps, and that step’sschemaIdtells you the exact schema the answer came from. Not every field inresultsis guaranteed an entry here.
callSteps outlines the steps (and the schema behind each), contributingCalls lists the calls inside them, and resultSources ties each answer to a call. callSteps is present on any completed request that involved a phone call, including PARTIAL and FAILURE. contributingCalls and resultSources are added on a SUCCESS or PARTIAL request, alongside callSteps (a single-call request included, which simply shows one step and one call). All are omitted for digital-only results and aren’t returned by the list endpoint.
There are two ways a request grows past a single call, and they show up differently across these fields:
- Re-dials of the same effort: one step, more than one call.
- Follow-up steps: more than one step, each with its own call(s), linked by
triggeredBy.
One step, more than one call (re-dials)
When SuperDial has to call the same line more than once to finish a single effort (a disconnect mid-call, or a callback to pick up where it left off), all of those calls belong to one step.callSteps still has a single entry, with numContributingCalls reflecting the count; the calls each get their own contributingCalls entry sharing that step’s callStep key; and resultSources points each field at whichever call actually produced it.
numContributingCalls is 2, both contributingCalls share callStep: "verification-of-benefits", and resultSources shows the split: planActive came from call 1, copay from the redial (call 2). To trace copay back to its source: resultSources.copay is 2 → contributingCalls[1] (the entry with call: 2, id: "3kW8yH2nR5tL9pM4vB0x") → its callStep is "verification-of-benefits" → that callSteps entry’s schemaId (fWxzG4nqtpHsJxS5Lm3q) is the schema that defined and captured it.
More than one step (follow-up)
When completing a request requires a distinct second effort (most commonly verifying benefits and then checking prior authorization on a separate call, often to a different line), that second effort is a new step.callSteps gains a second entry whose triggeredBy names the step it was opened off; the calls behind each step are tagged with the matching callStep; and resultSources maps each field across both steps.
callSteps shows what each step gathered, which schema gathered it (schemaId), and how it fared. The prior-authorization step’s triggeredBy points back at the benefits step that opened it. contributingCalls shows the actual calls, call 1 for benefits, call 2 for prior authorization (which dialed a different line, so it carries to), each identified by its own opaque id and also carrying that call’s full transcript, recordingDownloadUrl, and its own results (trimmed here for brevity). resultSources maps every answer to the call that produced it: planActive and copay came from call 1, priorAuthRequired and priorAuthNumber from call 2. Tracing priorAuthNumber: resultSources.priorAuthNumber is 2 → contributingCalls[1] (id: "3kW8yH2nR5tL9pM4vB0x", callStep: "prior-authorization") → the prior-authorization callSteps entry → its schemaId (qP2bN8rT6mK1xC3vW9aL), a different schema than the one that produced planActive.
Errors
All non-2xx responses use the uniform{error, message, [details]} envelope.
Listing requests
GET /v1/requests returns multiple requests, filtered by query parameters:
GET /v1/requests for the full request schema and per-language code samples.
Response
RequestResponse schema. Sorted by dateCreated descending (most recent first).
The list endpoint omits
transcript, transcriptPostCall, and recordingDownloadUrl, along with the per-call callSteps, contributingCalls, and resultSources. 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
When
requestBatchId is provided, dateFrom and dateTo are ignored. When requestBatchId is not provided, dateFrom and dateTo default to today’s window.
By batch
PassrequestBatchId as a query parameter to fetch every request under a given batch, regardless of their individual state, useful for tracking progress.
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.
Reading after a webhook
The recommended end-to-end pattern is:- Create a request with
internalIdso you can correlate. - Receive the webhook when the request reaches a terminal state.
- Call
GET /v1/requests/{requestId}to fetch the full result.
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 FAILURE.