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).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/superdial-requests-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
description: SuperDial REST API Reference
version: 1.0.0
title: SuperDial Requests API
servers:
- url: https://robodialer-service-api-9nc4t1p9.uc.gateway.dev
description: Production
tags:
- 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).
paths:
/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/CreateRequestBatchResponse'
examples:
singleInternalError:
summary: 'Single: unexpected server failure'
value:
error: INTERNAL_ERROR
message: An internal error occurred. Please try again or contact support if the problem persists.
payerLookupFailure:
summary: 'Payer phone number lookup: matched a payer but no phone on file, or transient infra failure. Retry with backoff.'
value:
error: PAYER_LOOKUP_FAILURE
message: Could not retrieve a phone number for the resolved payer. Please retry, or supply phoneNumber explicitly.
batchInternalError:
summary: 'Batch: exception raised mid-processing (most common). Top-level `ApiError` envelope, no `requests` key.'
value:
error: INTERNAL_ERROR
message: An internal error occurred. Please try again or contact support if the problem persists.
batchAllServerErrors:
summary: 'Batch: every entry failed and at least one was a server error (rarer; per-entry shape). Server-error entries surface as `INVALID_REQUEST` with the underlying message (the per-entry translator does not propagate `INTERNAL_ERROR`).'
value:
requests:
- error: INVALID_REQUEST
message: Failed to enqueue request
- error: INVALID_REQUEST
message: schemaId is required
operationId: postV1Requests
x-operation-id-source: derived
get:
tags:
- Requests
summary: List Requests
description: Retrieve requests filtered by date range or batch ID.
security:
- bearerAuth: []
parameters:
- name: dateFrom
in: query
required: false
schema:
type: string
format: date
description: '**Optional.** Start of the `dateCreated` window (inclusive), `YYYY-MM-DD`. Interpreted as UTC midnight. When omitted (and `requestBatchId` is also omitted), defaults to today in the server''s clock.'
- name: dateTo
in: query
required: false
schema:
type: string
format: date
description: '**Optional.** End of the `dateCreated` window (**exclusive**), `YYYY-MM-DD`. Interpreted as UTC midnight. When omitted (and `requestBatchId` is also omitted), defaults to tomorrow in the server''s clock.'
- name: requestBatchId
in: query
required: false
schema:
type: string
description: '**Optional.** Return every request belonging to this `requestBatchId`. Bypasses the `dateFrom`/`dateTo` defaults. Passing this returns matching requests regardless of when they were created.'
responses:
'200':
description: List of requests. The list endpoint omits `transcript`, `transcriptPostCall`, and `recordingDownloadUrl`. Fetch `GET /v1/requests/{requestId}` for those. Every other field on `RequestResponse` (including `state`, `modality`, `data_completeness`, `error`) is included when applicable.
content:
application/json:
schema:
type: object
properties:
requests:
type: array
items:
$ref: '#/components/schemas/RequestResponse'
examples:
list:
summary: Four requests showing one of each state (SUCCESS, PARTIAL, FAILURE, PROCESSING)
value:
requests:
- requestId: 8bF7xK2mP9qR4sT6uV0w
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
schemaId: fWxzG4nqtpHsJxS5Lm3q
requestType: claim-status
state: SUCCESS
inputs:
payerName: Sample Insurance Co
memberId: TEST123456789
patientFirstName: Sample
patientLastName: Patient
patientDateOfBirth: '1990-01-15'
beginningDateOfService: '2026-03-15'
billingProviderName: Test Clinic LLC
billingProviderTaxId: '999999999'
renderingProviderName: Dr Test Provider
renderingProviderNpi: '1234567890'
claimChargeAmount: '150.00'
phoneNumber: '2125551234'
results:
claimStatus: PAID
paidAmount: '150.00'
checkNumber: CHK998877
paidDate: '2026-04-10'
missingFields: []
dateCreated: '2026-04-24T15:30:00.123456+00:00'
completedAt: '2026-04-24T15:32:18.987654+00:00'
dueDate: '2026-04-25T23:00:00+00:00'
internalId: claim_internal_001
internalTag: march-batch
modality: phone_only
data_completeness: null
error: null
to: '+12125551234'
callDuration: 00:08:42
callSummary: Verified claim status as PAID.
- requestId: kT9bR2mP6nE3yV1xD7Aq
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
schemaId: fWxzG4nqtpHsJxS5Lm3q
requestType: claim-status
state: PARTIAL
inputs:
payerName: Sample Insurance Co
memberId: TEST555444333
patientFirstName: Sample
patientLastName: Patient
patientDateOfBirth: '1990-01-15'
beginningDateOfService: '2026-03-15'
billingProviderName: Test Clinic LLC
billingProviderTaxId: '999999999'
renderingProviderName: Dr Test Provider
renderingProviderNpi: '1234567890'
claimChargeAmount: '150.00'
phoneNumber: '2125551234'
results:
claimStatus: PAID
paidAmount: '150.00'
missingFields:
- checkNumber
- paidDate
dateCreated: '2026-04-24T15:33:10.123000+00:00'
completedAt: '2026-04-24T15:36:42.456000+00:00'
dueDate: '2026-04-25T23:00:00+00:00'
internalId: claim_internal_002
internalTag: march-batch
modality: digital_plus_phone
data_completeness: null
error: null
to: '+12125551234'
callDuration: 00:06:24
callSummary: Confirmed the claim is PAID for $150.00 on the primary call; a follow-up call for the check number and paid date did not complete.
- requestId: nQ4rW8sT1vY3zE5xC2bV
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
schemaId: fWxzG4nqtpHsJxS5Lm3q
requestType: claim-status
state: FAILURE
inputs:
payerName: Sample Insurance Co
memberId: BADID000
patientFirstName: Sample
patientLastName: Patient
patientDateOfBirth: '1990-01-15'
beginningDateOfService: '2026-03-15'
billingProviderName: Test Clinic LLC
billingProviderTaxId: '999999999'
renderingProviderName: Dr Test Provider
renderingProviderNpi: '1234567890'
claimChargeAmount: '150.00'
phoneNumber: '2125551234'
results: {}
missingFields: []
dateCreated: '2026-04-24T15:32:00.000000+00:00'
completedAt: '2026-04-24T15:35:11.222333+00:00'
dueDate: '2026-04-25T23:00:00+00:00'
internalId: claim_internal_003
internalTag: march-batch
modality: phone_only
data_completeness: null
error:
errorCategory: NOT_FOUND
errorCode: MEMBER_NOT_FOUND
errorMessage: Member could not be located
to: '+12125551234'
callDuration: 00:04:11
callSummary: Representative could not locate the member; lookup failed.
- requestId: aC3hN5jD8eL1fM2gK6Yo
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
schemaId: fWxzG4nqtpHsJxS5Lm3q
requestType: claim-status
state: PROCESSING
inputs:
payerName: Sample Insurance Co
memberId: TEST987654321
patientFirstName: Sample
patientLastName: Patient
patientDateOfBirth: '1990-01-15'
beginningDateOfService: '2026-03-15'
billingProviderName: Test Clinic LLC
billingProviderTaxId: '999999999'
renderingProviderName: Dr Test Provider
renderingProviderNpi: '1234567890'
claimChargeAmount: '150.00'
phoneNumber: '2125551234'
results: {}
missingFields: []
dateCreated: '2026-04-24T15:31:02.456789+00:00'
completedAt: null
dueDate: '2026-04-25T23:00:00+00:00'
internalId: claim_internal_004
internalTag: march-batch
modality: null
data_completeness: null
error: null
empty:
summary: No requests matched the window
value:
requests: []
'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
'400':
description: Invalid query parameter.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
invalidDateFrom:
summary: '`dateFrom` is not a valid `YYYY-MM-DD` date'
value:
error: INVALID_REQUEST
message: dateFrom must be a YYYY-MM-DD date.
invalidDateTo:
summary: '`dateTo` is not a valid `YYYY-MM-DD` date'
value:
error: INVALID_REQUEST
message: dateTo must be a YYYY-MM-DD date.
'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. Retry once; escalate if persistent.
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.
operationId: getV1Requests
x-operation-id-source: derived
/v1/requests/{requestId}:
get:
tags:
- Requests
summary: Retrieve a Request
description: Fetch details for a request by ID.
security:
- bearerAuth: []
parameters:
- name: requestId
in: path
required: true
schema:
type: string
description: The request ID
responses:
'200':
description: Request retrieved successfully. Single-request reads include phone-call enrichment fields (`transcript`, `recordingDownloadUrl`, etc.) when a representative call has completed.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestResponse'
examples:
success:
summary: 'Successfully retrieved a request that completed with results: every required field populated.'
value:
requestId: 8bF7xK2mP9qR4sT6uV0w
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
schemaId: fWxzG4nqtpHsJxS5Lm3q
requestType: claim-status
state: SUCCESS
inputs:
payerName: Sample Insurance Co
memberId: TEST123456789
patientFirstName: Sample
patientLastName: Patient
patientDateOfBirth: '1990-01-15'
beginningDateOfService: '2026-03-15'
billingProviderName: Test Clinic LLC
billingProviderTaxId: '999999999'
renderingProviderName: Dr Test Provider
renderingProviderNpi: '1234567890'
claimChargeAmount: '150.00'
phoneNumber: '2125551234'
results:
claimStatus: PAID
paidAmount: '150.00'
checkNumber: CHK998877
paidDate: '2026-04-10'
missingFields: []
dateCreated: '2026-04-24T15:30:00.123456+00:00'
completedAt: '2026-04-24T15:32:18.987654+00:00'
dueDate: '2026-04-25T23:00:00+00:00'
internalId: claim_internal_001
internalTag: march-batch
modality: phone_only
data_completeness: null
error: null
to: '+12125551234'
transcript: 'SuperDial Agent: Hi, I''m calling to check on a claim status for member TEST123456789.
Representative: Let me look that up for you...'
recordingDownloadUrl: https://storage.googleapis.com/sd-recordings/.../recording.mp3?X-Goog-Signature=...
callDuration: 00:08:42
callSummary: 'Verified claim status as PAID. Check #CHK998877 issued on 2026-04-10 for $150.00.'
callAuditSummary: All claim status questions answered. Representative confirmed paid amount and check number.
successDigitalOnly:
summary: 'SUCCESS via digital channels only: `data_completeness` is `"minimum"` to flag that a phone call could have yielded richer data.'
value:
requestId: rD2bV4mK7nE9yX1cP5Lo
requestBatchId: pH9kJ2lM4nB6vC8xZ7Qr
schemaId: fWxzG4nqtpHsJxS5Lm3q
requestType: claim-status
state: SUCCESS
inputs:
payerName: Sample Insurance Co
memberId: TEST111222333
patientFirstName: Sample
patientLastName: Patient
patientDateOfBirth: '1990-01-15'
beginningDateOfService: '2026-03-15'
billingProviderName: Test Clinic LLC
billingProviderTaxId: '999999999'
renderingProviderName: Dr Test Provider
renderingProviderNpi: '1234567890'
claimChargeAmount: '150.00'
phoneNumber: '2125551234'
results:
claimStatus: PAID
paidAmount: '150.00'
checkNumber: CHK112233
paidDate: '2026-04-12'
missingFields: []
dateCreated: '2026-04-24T15:35:00.123456+00:00'
completedAt: '2026-04-24T15:35:08.456789+00:00'
dueDate: '2026-04-25T23:00:00+00:00'
internalId: claim_internal_005
internalTag: march-batch
modality: digital_only
data_completeness: minimum
error: null
failureNoResults:
summary: 'FAILURE: payer rejected the lookup outright. `state: "FAILURE"`, `results` is empty (no fields ever captured), `error` describes the cause.'
value:
request
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/superdial/refs/heads/main/openapi/superdial-requests-api-openapi.yml