Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.0.0
info:
description: SuperDial REST API Reference
version: 1.0.0
title: SuperDial API
servers:
- url: https://robodialer-service-api-9nc4t1p9.uc.gateway.dev
description: Production
tags:
- name: Authentication
description: 'SuperDial employs Bearer Authentication. Fetch a bearer token using your API Key and API
Secret, then pass it as `Authorization: Bearer <token>` on subsequent calls.'
- name: Requests
description: Endpoints for creating and reading requests (structured data extraction jobs). All non-2xx
responses use the uniform `{error, message, [details]}` envelope (see the `ApiError` schema).
- name: Schemas
description: Discover the schemas provisioned for your account and the required input keys for each.
All non-2xx responses use the uniform `{error, message, [details]}` envelope (see the `ApiError` schema).
paths:
/v1/auth:
get:
summary: Authenticate and get token
description: 'Returns a short-lived bearer token for use in API calls. The API key and API secret
are **two distinct values** issued together: the key identifies your account, the secret authenticates
the request.'
tags:
- Authentication
security:
- apiKey: []
apiSecret: []
x-codeSamples:
- lang: shell
label: curl
source: "curl https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/auth \\\n -H 'Robodialer-API-Key:\
\ <your-api-key>' \\\n -H 'Robodialer-API-Secret: <your-api-secret>'"
- lang: python
label: Python
source: "import requests\n\nr = requests.get(\n 'https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/auth',\n\
\ headers={\n 'Robodialer-API-Key': '<your-api-key>',\n 'Robodialer-API-Secret':\
\ '<your-api-secret>',\n },\n)\nr.raise_for_status()\ntoken = r.json()['token']"
- lang: javascript
label: JavaScript
source: "const r = await fetch(\n 'https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/auth',\n\
\ {\n headers: {\n 'Robodialer-API-Key': '<your-api-key>',\n 'Robodialer-API-Secret':\
\ '<your-api-secret>',\n },\n },\n);\nconst { token } = await r.json();"
responses:
'200':
description: Token returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AuthTokenResponse'
example:
token: eyJhbGciOiJSUzI1NiIs...truncated...signature
'401':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleErrorResponse'
examples:
missingApiKey:
summary: Missing Robodialer-API-Key header
value:
error: MISSING_API_KEY
missingApiSecret:
summary: Missing Robodialer-API-Secret header
value:
error: MISSING_API_SECRET
invalidApiKey:
summary: API key not recognized
value:
error: INVALID_API_KEY
unauthorized:
summary: Secret does not match the API key
value:
error: UNAUTHORIZED
/v1/schemas:
get:
tags:
- Schemas
summary: List schemas
description: Returns the schemas provisioned for your account. Each row carries a `requestType`
(e.g. `claim-status`, `vob`) that identifies the kind of extraction the schema performs. Schemas
that are no longer accessible for your account are filtered out.
security:
- bearerAuth: []
responses:
'200':
description: List of schemas the caller's account is provisioned for.
content:
application/json:
schema:
$ref: '#/components/schemas/ListSchemasResponse'
example:
schemas:
- schemaId: fWxzG4nqtpHsJxS5Lm3q
name: Claim Status (Commercial)
requestType: claim-status
- schemaId: qP2bN8rT6mK1xC3vW9aL
name: Verification of Benefits
requestType: vob
'401':
description: 'Unauthorized: enforced by the API gateway. Returned when the `Authorization: Bearer
<token>` header is missing, malformed, or the token is invalid/expired.'
headers:
WWW-Authenticate:
description: Bearer realm and (when applicable) error code per RFC 6750.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayErrorResponse'
examples:
missingAuth:
summary: No Authorization header
value:
code: 401
message: Jwt is missing
malformedJwt:
summary: Authorization header value isn't a valid JWT
value:
code: 401
message: Jwt is not in the form of Header.Payload.Signature with two dots and 3 sections
'404':
description: 'Account not found: the API key does not resolve to a provisioned account.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error: ACCOUNT_NOT_FOUND
message: No account is associated with this API key. Contact support if you believe this
is an error.
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error: INTERNAL_ERROR
message: An internal error occurred. Please try again or contact support if the problem
persists.
/v1/schemas/{schemaId}/required-inputs:
get:
tags:
- Schemas
summary: Required inputs for a schema
description: 'Returns the input keys required and optionally accepted to submit a request against
this schema. Field names are returned verbatim. Use them as the keys of the `inputs` object on
`POST /v1/requests`. Lists are sorted. This is the baseline: if your account is enabled for per-payer
required inputs, some payers require additional fields not listed here, reported as `INVALID_INPUTS`
on `POST /v1/requests`.'
security:
- bearerAuth: []
parameters:
- name: schemaId
in: path
required: true
schema:
type: string
description: The schema ID (from `GET /v1/schemas`). Must be non-blank, ≤1500 characters, contain
no `/`, and must not start with `_` or `.`.
responses:
'200':
description: Sorted list of required input field names for this schema.
content:
application/json:
schema:
$ref: '#/components/schemas/RequiredInputsResponse'
example:
schemaId: fWxzG4nqtpHsJxS5Lm3q
requiredInputs:
fields:
- beginningDateOfService
- billingProviderName
- billingProviderTaxId
- claimChargeAmount
- memberId
- patientDateOfBirth
- patientFirstName
- patientLastName
- payerName
- phoneNumber
- renderingProviderName
- renderingProviderNpi
optionalInputs:
fields:
- memberId2
'400':
description: Invalid `schemaId` path parameter (empty, contains `/`, starts with `_` or `.`,
or exceeds 1500 characters).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error: INVALID_REQUEST
message: The provided schemaId is invalid.
'401':
description: 'Unauthorized: enforced by the API gateway. Returned when the `Authorization: Bearer
<token>` header is missing, malformed, or the token is invalid/expired.'
headers:
WWW-Authenticate:
description: Bearer realm and (when applicable) error code per RFC 6750.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayErrorResponse'
examples:
missingAuth:
summary: No Authorization header
value:
code: 401
message: Jwt is missing
'404':
description: Schema not found, or account not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
schemaNotFound:
summary: Schema not found, or has been retired and is no longer available for new requests
value:
error: SCHEMA_NOT_FOUND
message: No schema with that ID exists for your account.
accountNotFound:
summary: 'The API key resolves to an account that no longer exists. Rare: wrong-API-key
cases hit `INVALID_API_KEY` at `/v1/auth` first.'
value:
error: ACCOUNT_NOT_FOUND
message: No account is associated with this API key. Contact support if you believe
this is an error.
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error: INTERNAL_ERROR
message: An internal error occurred. Please try again or contact support if the problem
persists.
/v1/schemas/{schemaId}/required-payer-inputs:
post:
tags:
- Schemas
summary: Resolve payer names against a schema's required inputs
description: 'Given a schema and a batch of payer names, returns the schema''s own required/optional
inputs **plus** the per-payer required inputs for each name, so you can assemble the complete
input set for a specific payer *before* calling `POST /v1/requests`, instead of discovering a
payer-specific field from an `INVALID_INPUTS` rejection. The schema-level `requiredInputs`/`optionalInputs`
are identical in shape and meaning to [`GET /v1/schemas/{schemaId}/required-inputs`](/api-reference/schemas/required-inputs-for-a-schema);
`payers` adds the per-payer detail.
The response carries one `payers` entry per `payerNames` entry, in input order, with no de-duplication
(positionally aligned 1:1 with the request array). Each entry is either **matched** (`inputPayerName`,
`matchedPayerName`, `payerRequiredInputs.fields`) or a per-payer **error** (`inputPayerName`,
`errorCode`, `message`). Discriminate on the presence of `errorCode`. A per-payer failure never
fails the whole request; whole-request failures use the uniform `{error, message}` envelope.
**Opt-in.** Gated on the `enforcePayerRequiredInputs` account feature. When it is off the endpoint
returns 403 `PAYER_REQUIRED_INPUTS_DISABLED`. This is the schema-keyed twin of `POST /v1/scripts/{scriptId}/required-payer-inputs`.
See the [Per-Payer Required Inputs guide](/guides/payer-required-inputs).'
security:
- bearerAuth: []
parameters:
- name: schemaId
in: path
required: true
schema:
type: string
description: The schema ID (from `GET /v1/schemas`). Must be non-blank, ≤1500 characters, contain
no `/`, and must not start with `_` or `.`.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RequiredPayerInputsRequest'
example:
payerNames:
- Sample Insurance Co
- Unknown Payer
responses:
'200':
description: Schema required/optional inputs plus one `payers` entry per requested name.
content:
application/json:
schema:
$ref: '#/components/schemas/RequiredPayerInputsResponse'
example:
schemaId: fWxzG4nqtpHsJxS5Lm3q
requiredInputs:
fields:
- beginningDateOfService
- billingProviderName
- billingProviderTaxId
- claimChargeAmount
- memberId
- patientDateOfBirth
- patientFirstName
- patientLastName
- payerName
- phoneNumber
- renderingProviderName
- renderingProviderNpi
optionalInputs:
fields:
- memberId2
payers:
- inputPayerName: Sample Insurance Co
matchedPayerName: Sample Insurance Company, Inc.
payerRequiredInputs:
fields:
- claimNumber
- inputPayerName: Unknown Payer
errorCode: PAYER_NOT_FOUND
message: No canonical payer matched 'Unknown Payer'.
'400':
description: 'Invalid `schemaId` path parameter, or a malformed request body. Whole-request
only: a bad *individual* payer name comes back inline as a `payers[]` error entry, not a 400.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
invalidSchemaId:
summary: schemaId is empty, contains `/`, starts with `_` or `.`, or exceeds 1500 characters
value:
error: INVALID_REQUEST
message: The provided schemaId is invalid.
bodyNotObject:
summary: Body is missing or not a JSON object
value:
error: INVALID_REQUEST
message: Request body must be a JSON object.
payerNamesNotArray:
summary: '`payerNames` is absent or not an array'
value:
error: INVALID_REQUEST
message: '`payerNames` must be a JSON array of strings.'
payerNamesEmpty:
summary: '`payerNames` is an empty array'
value:
error: INVALID_REQUEST
message: '`payerNames` must contain at least one entry.'
payerNamesTooMany:
summary: '`payerNames` exceeds the 50-entry cap (no truncation: the whole request is
rejected)'
value:
error: INVALID_REQUEST
message: '`payerNames` may not exceed 50 entries.'
'401':
description: 'Unauthorized: enforced by the API gateway. Returned when the `Authorization: Bearer
<token>` header is missing, malformed, or the token is invalid/expired.'
headers:
WWW-Authenticate:
description: Bearer realm and (when applicable) error code per RFC 6750.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayErrorResponse'
examples:
missingAuth:
summary: No Authorization header
value:
code: 401
message: Jwt is missing
'403':
description: 'Per-payer required inputs is not enabled for your account. Opt-in feature: contact
your account manager.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error: PAYER_REQUIRED_INPUTS_DISABLED
message: Payer-required inputs are available as an opt-in feature but are not currently
enabled for your account. Reach out to your account manager to request access.
'404':
description: Schema not found, or account not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
schemaNotFound:
summary: Schema not found, or has been retired and is no longer available for new requests
value:
error: SCHEMA_NOT_FOUND
message: No schema with that ID exists for your account.
accountNotFound:
summary: 'The API key resolves to an account that no longer exists. Rare: wrong-API-key
cases hit `INVALID_API_KEY` at `/v1/auth` first.'
value:
error: ACCOUNT_NOT_FOUND
message: No account is associated with this API key. Contact support if you believe
this is an error.
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error: INTERNAL_ERROR
message: An internal error occurred. Please try again or contact support if the problem
persists.
/v1/requests:
post:
tags:
- Requests
summary: Create a Request
description: 'Submit a single request or a batch of requests. For batch, wrap in `{"requests": [...]}`.
If `internalId` is supplied on a single request, a duplicate POST with the same `internalId` returns
the previously reserved `requestId` rather than creating a new one.'
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateRequestPayload'
- $ref: '#/components/schemas/CreateRequestBatchPayload'
examples:
single:
summary: Single request
value:
schemaId: fWxzG4nqtpHsJxS5Lm3q
inputs:
payerName: Sample Insurance Co
memberId: TEST123456789
phoneNumber: '2125551234'
providerNpi: '1234567890'
dateOfService: '2026-03-15'
internalId: claim_internal_456
batch:
summary: 'Batch: multiple requests in one POST'
value:
requests:
- schemaId: fWxzG4nqtpHsJxS5Lm3q
inputs:
payerName: Sample Insurance Co
memberId: TEST123456789
phoneNumber: '2125551234'
providerNpi: '1234567890'
dateOfService: '2026-03-15'
internalId: claim_001
- schemaId: fWxzG4nqtpHsJxS5Lm3q
inputs:
payerName: Sample Insurance Co
memberId: TEST987654321
phoneNumber: '2125551234'
providerNpi: '1234567890'
dateOfService: '2026-03-12'
internalId: claim_002
responses:
'200':
description: Request(s) created successfully. The body is `CreateRequestSuccess` for a single-item
POST and `CreateRequestBatchResponse` (with every entry a success) for a batch.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateRequestSuccess'
- $ref: '#/components/schemas/CreateRequestBatchResponse'
examples:
single:
summary: 'Single: request created'
value:
requestId: 8bF7xK2mP9qR4sT6uV0w
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
internalId: claim_internal_456
singleWithPayerLookup:
summary: 'Single: request created, plus synchronous payer phone number lookup succeeded
(payerName supplied without phoneNumber)'
value:
requestId: 8bF7xK2mP9qR4sT6uV0w
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
internalId: claim_internal_456
payerLookup:
inputPayerName: Sample Insurance Co
inputPhoneNumber: null
matchedPayerName: Sample Insurance Company, Inc.
matchedPayerPhone: '8005551234'
phoneNumberToUse: '8005551234'
phoneNumberSource: superdial
singleIdempotentReplay:
summary: 'Single: idempotent replay (same internalId returns the original requestId)'
value:
requestId: 8bF7xK2mP9qR4sT6uV0w
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
internalId: claim_internal_456
batch:
summary: 'Batch: every entry created successfully'
value:
requests:
- requestId: 8bF7xK2mP9qR4sT6uV0w
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
internalId: claim_001
- requestId: aC3hN5jD8eL1fM2gK6Yo
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
internalId: claim_002
'207':
description: 'Partial success (batch only): at least one entry succeeded and at least one failed
(validation, lookup, or server error). Each failed entry uses the `ApiError` envelope; succeeded
entries use `CreateRequestSuccess`. The batch response itself does not carry a top-level error.'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRequestBatchResponse'
examples:
batchMixed:
summary: 'Batch: one entry created, one failed validation'
value:
requests:
- requestId: 8bF7xK2mP9qR4sT6uV0w
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
internalId: claim_001
- error: INVALID_REQUEST
message: schemaId is required
'400':
description: 'Validation error. The body is always an `ApiError` envelope, except when every
entry of a batch failed validation. In that case the body is a `CreateRequestBatchResponse`
and each entry is its own `ApiError`. Codes returned at this status: `INVALID_REQUEST` (payload-shape,
missing required fields, scheduling-capacity errors) and `INVALID_INPUTS` (input validation,
with `details.missingInputs` and/or `details.invalidInputs`). With per-payer required inputs
enabled, `details.missingInputs` can also include inputs a payer requires beyond the schema
fields.'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiError'
- $ref: '#/components/schemas/CreateRequestBatchResponse'
examples:
bodyNotJsonObject:
summary: Body is missing, empty, or not a JSON object (e.g. a JSON array)
value:
error: INVALID_REQUEST
message: The request body must be a JSON object.
schemaIdRequired:
summary: 'Single: schemaId missing'
value:
error: INVALID_REQUEST
message: schemaId is required
inputsNotObject:
summary: 'Single: inputs is not a JSON object'
value:
error: INVALID_REQUEST
message: inputs must be an object
inputsMissing:
summary: Required schema inputs are missing (details lists every missing field)
value:
error: INVALID_INPUTS
message: Required inputs are missing or invalid.
details:
missingInputs:
- beginningDateOfService
- billingProviderName
- billingProviderTaxId
- claimChargeAmount
- memberId
- patientDateOfBirth
- patientFirstName
- patientLastName
- phoneNumber
- renderingProviderName
- renderingProviderNpi
inputsInvalid:
summary: Required inputs missing AND format-invalid (details has both blocks)
value:
error: INVALID_INPUTS
message: Required inputs are missing or invalid.
details:
missingInputs:
- beginningDateOfService
- billingProviderName
- billingProviderTaxId
- claimChargeAmount
- patientDateOfBirth
- patientFirstName
- patientLastName
- renderingProviderName
- renderingProviderNpi
invalidInputs:
memberId: memberId contains invalid characters (curly braces)
phoneNumber: phoneNumber is not a valid U.S. phone number
inputsFormatInvalid:
summary: Format rules applied to supplied values. See the Input Validation guide for
every rule
value:
error: INVALID_INPUTS
message: Required inputs are missing or invalid.
details:
invalidInputs:
claimChargeAmount: claimChargeAmount is scientific notation
dateOfService: dateOfService is invalid
phoneNumber: phoneNumber is not a valid U.S. phone number
memberIdRejected:
summary: 'Member-ID validation (only when enabled for your account): here a BCBS payer
with a too-short memberId'
value:
error: INVALID_INPUTS
message: Required inputs are missing or invalid.
details:
invalidInputs:
memberId: memberId 'ABC' is too short to be a BCBS member ID (got 3 characters,
minimum is 9). BCBS Federal IDs are 9 chars (R + 8 digits); commercial IDs are
typically 11+.
dailyLimitZero:
summary: Daily call limit on the account is configured at 0
value:
error: INVALID_REQUEST
message: 'Daily calls limit is set to 0: cannot schedule batches'
capacityExceeded:
summary: Account is fully booked beyond the 365-day scheduling horizon
value:
error: INVALID_REQUEST
message: 'Could not schedule all rows within 365 days: 5 of 100 rows could not be
placed'
batchEmpty:
summary: 'Batch: requests array missing or empty'
value:
error: INVALID_REQUEST
message: The 'requests' array must contain at least one entry.
payerNotFound:
summary: 'Payer phone number lookup: `payerName` did not match any known payer (only
fires when `phoneNumber` was omitted).'
value:
error: PAYER_NOT_FOUND
message: Could not match the supplied payerName to any known payer.
batchAllFailed:
summary: 'Batch: every entry failed validation (per-entry envelopes; HTTP 400 because
no entry succeeded and no entry hit a server error). Note: schema-not-found surfaces
here as `INVALID_REQUEST` with the validator''s `Schema not found` message because
batch entries don''t carry status codes. Read `message` to distinguish 4xx causes.'
value:
requests:
- error: INVALID_REQUEST
message: Schema not found
- error: INVALID_REQUEST
message: schemaId is required
'401':
description: 'Unauthorized: enforced by the API gateway. Returned when the `Authorization: Bearer
<token>` header is missing, malformed, or the token is invalid/expired. The gateway uses its
own envelope (`{code, message}`), distinct from the service''s `ApiError`.'
headers:
WWW-Authenticate:
description: Bearer realm and (when applicable) error code per RFC 6750.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayErrorResponse'
examples:
missingAuth:
summary: No Authorization header
value:
code: 401
message: Jwt is missing
malformedJwt:
summary: Authorization header value isn't a valid JWT
value:
code: 401
message: Jwt is not in the form of Header.Payload.Signature with two dots and 3 sections
'404':
description: 'Resource not found: schema or account.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
schemaNotFound:
summary: schemaId does not exist for this account, or has been retired
value:
error: SCHEMA_NOT_FOUND
message: No schema with that ID exists for your account.
accountNotFound:
summary: 'The API key resolves to an account that no longer exists. Rare: wrong-API-key
cases hit `INVALID_API_KEY` at `/v1/auth` first.'
value:
error: ACCOUNT_NOT_FOUND
message: No account is associated with this API key. Contact support if you believe
this is an error.
'500':
description: 'Internal server error. **Single-item POST:** body is the top-level `INTERNAL_ERROR`
envelope. **Batch POST:** body can take **either** of two shapes: top-level `INTERNAL_ERROR`
envelope (the common case), or `{"requests": [...]}` with per-entry envelopes (rarer: every
entry failed and at least one was a server error). Check for the `requests` key to tell the
two shapes apart.'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiError'
- $ref: '#/components/schemas/CreateRequestBatchRes
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/superdial/refs/heads/main/openapi/superdial-api-openapi.yml