Request
A single data-extraction job against a payer. A request consists of aschemaId that defines the output fields and inputs that supply the values the schema requires. SuperDial fills the schema’s fields from one or more channels and returns the structured results object on GET /v1/requests/{requestId}, for example:
Schema
A definition of the output fields a request should produce, along with which fields are required. EachrequestType is backed by a schema. Schemas are configured by SuperDial and identified by schemaId.
When a request runs, SuperDial fills the schema’s fields from one or more sources and merges them into the request’s results. A request reaches the SUCCESS state when its call effort completes with every required field filled. Some requests take more than one call effort: for example, verifying benefits and then checking prior authorization on a separate call; when the first effort succeeds but a follow-up effort fails, the request ends in PARTIAL, with results holding what was captured and missingFields listing the rest. A request ends in FAILURE when its primary call effort fails.
You can discover the schemas provisioned for your account at any time with GET /v1/schemas, and look up the required input keys for a given schema with GET /v1/schemas/{schemaId}/required-inputs.
Request Type
The kind of extraction a schema performs, for example,claim-status or vob (verification of benefits). Each schema is configured for one requestType, and the value is server-derived: you don’t pass it on POST /v1/requests, but it surfaces on RequestResponse.requestType and on each row of GET /v1/schemas. Discover the request types your account is provisioned for via GET /v1/schemas.
Request Batch
A scheduling grouping. Every request belongs to a batch, identified byrequestBatchId:
- Submit
POST /v1/requestswith a single request → a batch of size 1 is created automatically with its ownrequestBatchId. - Submit
POST /v1/requestswith{ "requests": [...] }→ within that single submission, entries scheduled for the same business day share onerequestBatchId; entries scheduled for different days each get a distinctrequestBatchId. Whether the submission lands on one day or spills across several depends on your account’s daily call capacity and any work already pending on those days.
requestId and gets its own webhook regardless of which batch it belongs to.
You can list all requests under a given requestBatchId with GET /v1/requests?requestBatchId=.... For multi-day submissions, iterate over the unique IDs returned in the create response.
State
A request moves through four states. Values are uppercase on the response (SUCCESS, not success):
A webhook fires when the request transitions to
SUCCESS, PARTIAL, or FAILURE.
error object
Whenstate is FAILURE, the response carries a structured error object describing what went wrong. On PROCESSING, SUCCESS, and PARTIAL, error is null. A PARTIAL request’s primary effort succeeded, so it has no single failure cause; use missingFields to see what a follow-up didn’t capture.
The wording of
errorMessage may change between releases. Use errorCode for programmatic dispatch.errorCategory is one of:
errorCode
Machine-readable failure code withinerror.errorCategory. Match on this for parsing and analytics; errorMessage carries the human-readable detail.
The taxonomy has four groups: a small set of SYSTEM_ERROR codes, a handful of NOT_FOUND entity codes, and two field-specific NOT_FOUND families (*_MISSING and *_INCORRECT).
SYSTEM_ERROR codes
NOT_FOUND codes: entity
The payer couldn’t locate the entity the request asked about.
NOT_FOUND codes: missing required input
A required input wasn’t supplied with the request. Pattern: {FIELD}_MISSING.
CLAIM_NUMBER_MISSINGCLAIM_AUTHORIZATION_NUMBER_MISSINGCLAIM_CPT_PROCEDURE_CODE_MISSINGCLAIM_DATE_OF_SERVICE_MISSINGCLAIM_DIAGNOSIS_MISSINGCLAIM_EFT_CHECK_NUMBER_MISSINGMEMBER_GROUP_MISSINGMEMBER_PATIENT_LOCATION_MISSINGMEMBER_PATIENT_PHONE_MISSINGMEMBER_PAYER_SPECIFIC_PATIENT_ID_MISSINGMEMBER_POLICY_NUMBER_MISSINGMEMBER_SSN_MISSINGPROVIDER_CALLBACK_NUMBER_MISSINGPROVIDER_FACILITY_INFO_MISSINGPROVIDER_FACILITY_LOCATION_MISSINGPROVIDER_FAX_MISSINGPROVIDER_OTHER_LICENSING_MISSINGPROVIDER_PTAN_MISSINGPROVIDER_SPECIALTY_MISSING
NOT_FOUND codes: incorrect input value
An input was supplied but didn’t match the payer’s records. Pattern: {FIELD}_INCORRECT.
APPLICATION_ID_INCORRECTAPPLICATION_SUBMISSION_METHOD_INCORRECTAPPLICATION_SUBMITTED_DATE_INCORRECTAPPLICATION_SUBMITTED_TO_INCORRECTBEGINNING_DATE_OF_SERVICE_INCORRECTBILLING_PROVIDER_ADDRESS_INCORRECTBILLING_PROVIDER_NAME_INCORRECTBILLING_PROVIDER_NPI_INCORRECTBILLING_PROVIDER_TAX_ID_INCORRECTCALLBACK_NUMBER_INCORRECTCLAIM_CHARGE_AMOUNT_INCORRECTCLAIM_SUBMITTED_DATE_INCORRECTCLEARINGHOUSE_CLAIM_ID_INCORRECTCLEARINGHOUSE_NAME_INCORRECTEND_DATE_OF_SERVICE_INCORRECTFACILITY_NPI_INCORRECTFAX_NUMBER_INCORRECTGROUP_NUMBER_INCORRECTINPUT_PHONE_NUMBER_INCORRECTINTERNAL_CLAIM_ID_INCORRECTINTERNAL_ID_INCORRECTINTERNAL_PROVIDER_ID_INCORRECTINTERNAL_TAG_INCORRECTIS_PRIMARY_POLICY_INCORRECTMEDICATION_NAME_INCORRECTMEMBER_ADDRESS_INCORRECTMEMBER_DATE_OF_BIRTH_INCORRECTMEMBER_FIRST_NAME_INCORRECTMEMBER_ID_INCORRECTMEMBER_LAST_NAME_INCORRECTOFFICE_NPI_INCORRECTPATIENT_ADDRESS_INCORRECTPATIENT_DATE_OF_BIRTH_INCORRECTPATIENT_FIRST_NAME_INCORRECTPATIENT_LAST_NAME_INCORRECTPATIENT_PHONE_NUMBER_INCORRECTPATIENT_RELATIONSHIP_TO_MEMBER_INCORRECTPAYER_CLAIM_ID_INCORRECTPAYER_NAME_INCORRECTPHARMACY_NAME_INCORRECTPRACTICE_NPI_INCORRECTPRIOR_AUTH_ID_INCORRECTPROVIDER_SPECIALTY_INCORRECTPROVIDER_TYPE_INCORRECTPTAN_INCORRECTRENDERING_PROVIDER_ADDRESS_INCORRECTRENDERING_PROVIDER_FIRST_NAME_INCORRECTRENDERING_PROVIDER_LAST_NAME_INCORRECTRENDERING_PROVIDER_NPI_INCORRECTRENDERING_PROVIDER_PHONE_NUMBER_INCORRECTRENDERING_PROVIDER_SPECIALTY_INCORRECTREPRESENTATIVE_PHONE_NUMBER_INCORRECTSERVICE_STATE_INCORRECTTAX_ID_INCORRECT
Dialing-number errors
When a phone call fails because the dialed number was incorrect, the code and category depend on where that number came from — so you’re not blamed for a number SuperDial chose, and vice-versa:
Numbers SuperDial looked up (a directory match or an agent lookup) are classified as
SYSTEM_ERROR — the incorrect number is our fault. Numbers you supplied, or that a representative referred us to, are classified as NOT_FOUND.
Older calls placed before this attribution shipped, or calls where the number’s source wasn’t recorded, may still surface the generic
PHONE_NUMBER_INCORRECT code — under SYSTEM_ERROR when SuperDial looked up the number, otherwise NOT_FOUND. Handle both the generic and the provenance-specific codes.OTHER under NOT_FOUND
When the failure category is NOT_FOUND but no specific entity / *_MISSING / *_INCORRECT code fits.
Stability. Existing codes won’t be renamed. New codes may be introduced: new *_MISSING or *_INCORRECT codes appear when new schemas reference new fields. When bucketing for analytics, default unknown values to OTHER rather than dropping the row.
Payer
The insurance company a request asks about. Identify the payer withinputs.payerName. When the schema also requires inputs.phoneNumber, that’s the number SuperDial will dial.
If your account is enabled for payer phone number lookup (an opt-in capability, ask your account team), phoneNumber becomes optional: supply inputs.payerName alone and SuperDial will look up the dialing number for you. See the Payer Phone Number Lookup guide for what the lookup matches, what inputs shape the result (especially memberId for BCBS-family payers), and the failure modes (PAYER_NOT_FOUND, PAYER_LOOKUP_FAILURE).
When lookup is enabled, the POST /v1/requests response, and the GET /v1/requests reads, carry a payerLookup sub-object reporting the payer match and the number that will be dialed (phoneNumberToUse, plus phoneNumberSource). By default a phoneNumber you supply is always dialed as-is; set useMatchedPayerPhone: true to have SuperDial dial its matched number instead. See the Payer Phone Number Lookup guide for the full field reference.
If your account is enabled for per-payer required inputs (a separate opt-in capability, ask your account team), some payers require additional inputs beyond the schema’s fields, so what you must supply can depend on payerName. See the Per-Payer Required Inputs guide.
Modality
Themodality field on a RequestResponse records how the result was obtained, for billing audit and routing. SuperDial picks the modalities; you don’t address them directly.
The
phone_only and digital_plus_phone values both mean a phone call was placed and is billable at the phone-call rate. digital_only means no phone call was placed.
data_completeness
A coarse completeness tier for digital-only results. Currently the only non-null value is"minimum", which appears when state is SUCCESS and modality is digital_only, a hint that a phone-call attempt could have yielded richer data than what the electronic source returned. null in every other case. Reserved for future richer tiers (enhanced, complete).
Call steps
A request usually completes in a single phone call, but it can take more than one: for example, verifying benefits on one call and then checking prior authorization on a separate call. Every call rolls up into the one request: the merged answers land in the top-levelresults, and the request’s state reflects the whole.
On the single-request read, this shows up in related fields. callSteps summarizes the steps the request worked through, one per step, each naming the schema it ran via schemaId, and is present on any completed phone request. On a SUCCESS or PARTIAL request it’s joined by contributingCalls, which breaks out the individual calls behind those steps (each identified by an opaque id, plus that call’s transcript and captured fields: how it was gathered), and resultSources, which maps each result field to the call that produced it, and, through that call’s step, to the schema behind it.
A request grows past a single call in one of two ways: re-dials of the same effort (one step, more than one call, distinguished by numContributingCalls) or a follow-up step (a distinct second effort, e.g. prior authorization after benefits, that appears as a second callSteps entry linked back by triggeredBy). See Reading Requests → Calls behind a request for a worked example of each.
Webhook
An outbound HTTP POST that SuperDial sends to your endpoint when a request reaches a terminal state. See the Webhooks guide for payload, signature verification, and retry behavior.dueDate
The date a request is scheduled to run, as an ISO-8601 timestamp on theRequestResponse shape. Set at submission time based on your account’s daily call capacity and any work already pending. Use it to give end users a “ready by” estimate when you submit a batch, particularly when a batch overflows your daily capacity and lands across multiple business days. null when not set.
Timestamps
dateCreated, completedAt, and dueDate on a request response are ISO-8601 strings with an explicit UTC offset: for example, "2026-04-24T15:32:18.123456+00:00". They are emitted in UTC by the server.
Webhook payloads do not include any timestamps: they only carry requestId, requestBatchId, state, and the optional internalId/internalTag. To get timing data after a webhook fires, fetch the request via GET /v1/requests/{requestId} and read dateCreated/completedAt from the response.
dateFrom and dateTo query parameters on the list endpoint accept YYYY-MM-DD and are interpreted as UTC midnight. When omitted, they default to today’s UTC window. Pass explicit values if you need a deterministic range.
internalId
An optional correlation ID you supply when creating a request. SuperDial echoes it back on reads and webhooks so you can match requests to your own records. Also serves as an idempotency key. See Idempotency.internalTag
An optional opaque string you supply when creating a request. Echoed back on reads and webhooks. Useful for tagging requests (e.g.,"march-batch", "high-priority") without polluting your own correlation IDs.
Optional response fields
A couple of fields onGET /v1/requests/{requestId} are per-account additions that aren’t surfaced by default. If one of these doesn’t appear in your responses, the capability isn’t turned on for your account. Contact your account team if you’d like either enabled.
These fields are additive: a response that omits them has the same shape as one without them enabled. Your parser doesn’t need to branch on whether your account has them.
Single-request vs list response shapes
GET /v1/requests/{requestId} and GET /v1/requests (list) return the same RequestResponse schema, but the list endpoint omits the enrichment fields below, the transcript and recording fields (which can be large) and the per-call breakdown:
Other phone-enrichment fields (
to, callDuration, callFromNumber, callSummary, callAuditSummary) are included in both endpoints when applicable. If you need any of the list-omitted fields, fetch the single-request endpoint after locating the requestId.
Production vs Sandbox
Accounts can be provisioned with production and/or sandbox API key/secret pairs. Authenticating with a sandbox pair routes the request through SuperDial’s sandbox path: validation, idempotency, scheduling, and webhook delivery run identically to production, but phone-backed requests don’t dial a real number. Results are LLM-generated against your schema instead. See the Sandbox guide for the complete picture, including a recommended test plan.Webhooks are always signed with your production-side signing secret (your webhook secret if set, otherwise your production API key), even for sandbox requests. See Webhooks → Signature verification.