Definitions for the terms used throughout the API.
Request
A single data-extraction job against a payer. A request consists of a schemaId 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:
{ "claimStatus": "PAID", "paidAmount": "150.00" }
Schema
A definition of the output fields a request should produce, along with which fields are required. Each requestType 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 every required field has been filled; a request that runs to completion but is missing one or more required fields ends in PARTIAL (when some required fields were captured) or FAILURE (when nothing usable was captured), with missingFields populated.
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 by requestBatchId:
- Submit
POST /v1/requests with a single request → a batch of size 1 is created automatically with its own requestBatchId.
- Submit
POST /v1/requests with { "requests": [...] } → within that single submission, entries scheduled for the same business day share one requestBatchId; entries scheduled for different days each get a distinct requestBatchId. 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.
A batch affects when a request is scheduled to run and how progress is tracked across that day’s slice, but every request still has its own 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):
| State | Terminal? | Meaning |
|---|
PROCESSING | No | Still running. Wait for the webhook. |
SUCCESS | Yes | Completed with every required field populated. results is full, error is null. |
PARTIAL | Yes | Some required fields were captured but not all. results is partially populated, missingFields lists what’s missing, and error describes why the gap. |
FAILURE | Yes | No required fields were captured. results is empty and error describes the cause. |
SUCCESS, PARTIAL, or FAILURE.
error object
When state is PARTIAL or FAILURE, the response carries a structured error object describing what went wrong. On PROCESSING and SUCCESS, error is null.
| Field | Type | Description |
|---|
errorCategory | enum | Two-bucket category — see below. |
errorCode | enum | Machine-readable failure code within the category — see errorCode for the full list. |
errorMessage | string | Human-readable sentence describing what went wrong. See the note below on wording stability. |
The wording of errorMessage may change between releases — use errorCode for programmatic dispatch.
errorCategory is one of:
| Category | Meaning |
|---|
NOT_FOUND | The payer couldn’t find what you asked about. |
SYSTEM_ERROR | Any other failure — IVR navigation, payer refusal, unreachable, etc. |
errorCode
Machine-readable failure code within error.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
| Code | Triggers |
|---|
IVR_FAILURE | Couldn’t navigate the payer’s phone system to reach a representative (no rep-routing option, dead-end menus). |
PAYER_REFUSAL | Representative refused to provide the information — declined to interact with an automated agent, declined to speak with a third party, or refused the specific query. |
UNABLE_TO_REACH_HUMAN_IN_TIME | Couldn’t connect to a representative within the per-request retry budget — voicemail-only line, hold time exceeded, repeated long-wait attempts. |
REQUIRES_OTHER_CHANNEL | Payer requires the request through portal, fax, email, or another channel SuperDial doesn’t currently support. |
OTHER | A SYSTEM_ERROR that didn’t fit a more specific code. Inspect errorMessage for detail. |
NOT_FOUND codes — entity
The payer couldn’t locate the entity the request asked about.
| Code | Triggers |
|---|
MEMBER_NOT_FOUND | Member couldn’t be located from the supplied identifiers. |
PROVIDER_NOT_FOUND | Provider couldn’t be located. |
CLAIM_NOT_FOUND | Claim couldn’t be located. |
PRIOR_AUTH_NOT_FOUND | Prior authorization couldn’t be located. |
APPEAL_NOT_FOUND | Appeal couldn’t be located. |
{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
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_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_INCORRECTPHONE_NUMBER_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_INCORRECTSERVICE_STATE_INCORRECTTAX_ID_INCORRECT
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 with inputs.payerName. When the schema also requires inputs.phoneNumber, that’s the number SuperDial will dial.
If your account is enabled for payer-phone resolution (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 Resolution guide for what the resolver matches, what inputs shape the result (especially memberId for BCBS-family payers), and the failure modes (PAYER_NOT_FOUND, PAYER_LOOKUP_FAILURE).
When resolution runs and succeeds, the POST /v1/requests response — and the GET /v1/requests reads — carry a payerLookup sub-object echoing inputPayerName and the matched matchedPayerName. The resolved phone number is not returned: dialing happens server-side and is never echoed to clients.
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
The modality 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.
| Value | Meaning |
|---|
digital_only | Only electronic channels (clearinghouses, eligibility APIs) were attempted. No phone call placed. |
phone_only | Only a phone call was placed (no electronic attempt). |
digital_plus_phone | Both — electronic was attempted first, then a phone call. |
null | No modality has been dispatched yet — typical on a PROCESSING request that hasn’t started running. |
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).
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 the RequestResponse 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 on GET /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.
| Field | What it gives you |
|---|
transcriptPostCall | The post-call transcript (separate from the live transcript). |
callFromNumber | The outbound caller number (E.164) the call originated from. |
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 three enrichment fields that can be large:
| Field | Single GET | List GET |
|---|
transcript | ✓ | — |
transcriptPostCall | ✓ (when enabled) | — |
recordingDownloadUrl | ✓ | — |
to, callDuration, callFromNumber, callSummary, callAuditSummary) are included in both endpoints when applicable. If you need any of the three 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. 
