> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts & Glossary

> Definitions for the core terms used throughout the SuperDial API.

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:

```json theme={null}
{ "claimStatus": "PAID", "paidAmount": "150.00" }
```

A request has a [state](#state) lifecycle and emits a [webhook](/guides/webhooks) when it reaches a terminal state.

## 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](#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`](/api-reference/schemas/list-schemas), and look up the required input keys for a given schema with [`GET /v1/schemas/{schemaId}/required-inputs`](/api-reference/schemas/required-inputs-for-a-schema).

## Request Type

The kind of extraction a schema performs, for example, `claim-status` or `vob` (verification of benefits). Each [schema](#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`](/guides/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`](/guides/reading-requests#by-batch) 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](/guides/webhooks).                                                                                                                                                                                                                    |
| `SUCCESS`    | Yes       | Completed with every required field populated. `results` is full, `error` is `null`.                                                                                                                                                                                        |
| `PARTIAL`    | Yes       | The request's primary call effort succeeded but a follow-up call effort (e.g. a prior-authorization call placed after benefits) failed. `results` holds what the successful effort captured, `missingFields` lists what the failed follow-up didn't, and `error` is `null`. |
| `FAILURE`    | Yes       | No required fields were captured. `results` is empty and `error` describes the cause.                                                                                                                                                                                       |

A [webhook](/guides/webhooks) fires when the request transitions to `SUCCESS`, `PARTIAL`, or `FAILURE`.

## error object

When `state` 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.

| Field           | Type   | Description                                                                                       |
| --------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `errorCategory` | enum   | Two-bucket category (see below).                                                                  |
| `errorCode`     | enum   | Machine-readable failure code within the category. See [errorCode](#errorcode) for the full list. |
| `errorMessage`  | string | Human-readable sentence describing what went wrong. See the note below on wording stability.      |

<Note>
  The wording of `errorMessage` may change between releases. Use `errorCode` for programmatic dispatch.
</Note>

`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.                                                                                                                |
| `MATCHED_PHONE_NUMBER_INCORRECT` | SuperDial dialed a number from a payer-directory match or a SuperDial-agent lookup, and that number turned out to be incorrect. Attributed to SuperDial, not your input. See [Dialing-number errors](#dialing-number-errors). |
| `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.                               |

### `NOT_FOUND` codes: missing required input

A required input wasn't supplied with the request. Pattern: `{FIELD}_MISSING`.

* `CLAIM_NUMBER_MISSING`
* `CLAIM_AUTHORIZATION_NUMBER_MISSING`
* `CLAIM_CPT_PROCEDURE_CODE_MISSING`
* `CLAIM_DATE_OF_SERVICE_MISSING`
* `CLAIM_DIAGNOSIS_MISSING`
* `CLAIM_EFT_CHECK_NUMBER_MISSING`
* `MEMBER_GROUP_MISSING`
* `MEMBER_PATIENT_LOCATION_MISSING`
* `MEMBER_PATIENT_PHONE_MISSING`
* `MEMBER_PAYER_SPECIFIC_PATIENT_ID_MISSING`
* `MEMBER_POLICY_NUMBER_MISSING`
* `MEMBER_SSN_MISSING`
* `PROVIDER_CALLBACK_NUMBER_MISSING`
* `PROVIDER_FACILITY_INFO_MISSING`
* `PROVIDER_FACILITY_LOCATION_MISSING`
* `PROVIDER_FAX_MISSING`
* `PROVIDER_OTHER_LICENSING_MISSING`
* `PROVIDER_PTAN_MISSING`
* `PROVIDER_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_INCORRECT`
* `APPLICATION_SUBMISSION_METHOD_INCORRECT`
* `APPLICATION_SUBMITTED_DATE_INCORRECT`
* `APPLICATION_SUBMITTED_TO_INCORRECT`
* `BEGINNING_DATE_OF_SERVICE_INCORRECT`
* `BILLING_PROVIDER_ADDRESS_INCORRECT`
* `BILLING_PROVIDER_NAME_INCORRECT`
* `BILLING_PROVIDER_NPI_INCORRECT`
* `BILLING_PROVIDER_TAX_ID_INCORRECT`
* `CALLBACK_NUMBER_INCORRECT`
* `CLAIM_CHARGE_AMOUNT_INCORRECT`
* `CLAIM_SUBMITTED_DATE_INCORRECT`
* `CLEARINGHOUSE_CLAIM_ID_INCORRECT`
* `CLEARINGHOUSE_NAME_INCORRECT`
* `END_DATE_OF_SERVICE_INCORRECT`
* `FACILITY_NPI_INCORRECT`
* `FAX_NUMBER_INCORRECT`
* `GROUP_NUMBER_INCORRECT`
* `INPUT_PHONE_NUMBER_INCORRECT`
* `INTERNAL_CLAIM_ID_INCORRECT`
* `INTERNAL_ID_INCORRECT`
* `INTERNAL_PROVIDER_ID_INCORRECT`
* `INTERNAL_TAG_INCORRECT`
* `IS_PRIMARY_POLICY_INCORRECT`
* `MEDICATION_NAME_INCORRECT`
* `MEMBER_ADDRESS_INCORRECT`
* `MEMBER_DATE_OF_BIRTH_INCORRECT`
* `MEMBER_FIRST_NAME_INCORRECT`
* `MEMBER_ID_INCORRECT`
* `MEMBER_LAST_NAME_INCORRECT`
* `OFFICE_NPI_INCORRECT`
* `PATIENT_ADDRESS_INCORRECT`
* `PATIENT_DATE_OF_BIRTH_INCORRECT`
* `PATIENT_FIRST_NAME_INCORRECT`
* `PATIENT_LAST_NAME_INCORRECT`
* `PATIENT_PHONE_NUMBER_INCORRECT`
* `PATIENT_RELATIONSHIP_TO_MEMBER_INCORRECT`
* `PAYER_CLAIM_ID_INCORRECT`
* `PAYER_NAME_INCORRECT`
* `PHARMACY_NAME_INCORRECT`
* `PRACTICE_NPI_INCORRECT`
* `PRIOR_AUTH_ID_INCORRECT`
* `PROVIDER_SPECIALTY_INCORRECT`
* `PROVIDER_TYPE_INCORRECT`
* `PTAN_INCORRECT`
* `RENDERING_PROVIDER_ADDRESS_INCORRECT`
* `RENDERING_PROVIDER_FIRST_NAME_INCORRECT`
* `RENDERING_PROVIDER_LAST_NAME_INCORRECT`
* `RENDERING_PROVIDER_NPI_INCORRECT`
* `RENDERING_PROVIDER_PHONE_NUMBER_INCORRECT`
* `RENDERING_PROVIDER_SPECIALTY_INCORRECT`
* `REPRESENTATIVE_PHONE_NUMBER_INCORRECT`
* `SERVICE_STATE_INCORRECT`
* `TAX_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:

| Dialed number came from                                                    | `errorCategory` | `errorCode`                             |
| -------------------------------------------------------------------------- | --------------- | --------------------------------------- |
| SuperDial payer-directory match, or a SuperDial-agent lookup               | `SYSTEM_ERROR`  | `MATCHED_PHONE_NUMBER_INCORRECT`        |
| A number a representative referred us to (from an earlier call)            | `NOT_FOUND`     | `REPRESENTATIVE_PHONE_NUMBER_INCORRECT` |
| The number you supplied in `inputs.phoneNumber` (or a configured override) | `NOT_FOUND`     | `INPUT_PHONE_NUMBER_INCORRECT`          |

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`.

<Note>
  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.
</Note>

### `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 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](/guides/payer-resolution) 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](/guides/payer-resolution) 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](/guides/payer-required-inputs).

## 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. |

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-level `results`, 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](/guides/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](/guides/webhooks) for payload, signature verification, and retry behavior.

## dueDate

The date a request is scheduled to run, as an ISO-8601 timestamp on the [`RequestResponse`](/api-reference/requests/retrieve-a-request) 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](/guides/webhooks#payload) 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}`](/guides/reading-requests#single-request) and read `dateCreated`/`completedAt` from the response.

`dateFrom` and `dateTo` query parameters on the [list endpoint](/guides/reading-requests#listing-requests) 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](/guides/creating-a-request#correlation-and-idempotency). 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](/guides/creating-a-request#correlation-and-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.    |

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`](/api-reference/requests/retrieve-a-request) schema, but the **list endpoint omits the enrichment fields below**, the transcript and recording fields (which can be large) and the per-call breakdown:

| Field                  | Single GET       | List GET |
| ---------------------- | ---------------- | -------- |
| `transcript`           | ✓                | Omitted  |
| `transcriptPostCall`   | ✓ (when enabled) | Omitted  |
| `recordingDownloadUrl` | ✓                | Omitted  |
| `callSteps`            | ✓                | Omitted  |
| `contributingCalls`    | ✓                | Omitted  |
| `resultSources`        | ✓                | Omitted  |

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](/guides/sandbox) for the complete picture, including a recommended test plan.

<Note>
  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](/guides/webhooks#signature-verification).
</Note>