Creating a Request

POST /v1/requests creates one or more requests and returns their IDs. The body shape varies based on whether you’re submitting a single item or a batch.

Authentication

Protected routes require a bearer token, including POST /v1/requests and the other /v1/requests* endpoints. Get one with GET /v1/auth (passing your API key and secret as the Robodialer-API-Key and Robodialer-API-Secret headers). Pass the returned token as Authorization: Bearer <token> on every subsequent HTTP request. Tokens are valid for 1 hour. Refresh by calling GET /v1/auth again; there’s no refresh-token flow. For long-running batches or background workers, fetch a fresh token at the start of each work cycle, or refresh on 401 responses.

import requests

def fetch_token(api_key: str, api_secret: str) -> str:
    r = requests.get(
        "https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/auth",
        headers={
            "Robodialer-API-Key": api_key,
            "Robodialer-API-Secret": api_secret,
        },
    )
    r.raise_for_status()
    return r.json()["token"]

Single request

Submit a single request by sending a JSON body with the request’s fields directly:

curl -X POST https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/requests \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
    "inputs": {
      "payerName": "Sample Insurance Co",
      "memberId": "TEST123456789",
      "phoneNumber": "2125551234",
      "providerNpi": "1234567890",
      "dateOfService": "2026-03-15"
    },
    "internalId": "claim_internal_456"
  }'

Response

{
  "requestId": "8bF7xK2mP9qR4sT6uV0w",
  "requestBatchId": "pH9kJ2lM4nB6vC8xZ7Qr",
  "internalId": "claim_internal_456"
}

If your account is enabled for payer phone number lookup (opt-in: ask your account team), the response carries a payerLookup sub-object describing the payer/phone lookup for the request.

{
  "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"
  }
}

payerLookup is always present on the response and reports the number that will be dialed (phoneNumberToUse) and where it came from (phoneNumberSource: superdial, phoneBook, or input). The matched* fields are populated only when SuperDial dials its own matched number; if your supplied phoneNumber is dialed, they’re null and phoneNumberSource is "input". By default a supplied phoneNumber always wins: set useMatchedPayerPhone: true to dial the matched number instead. The same block is returned on reads. See the Payer Phone Number Lookup guide for the full field reference. The request begins running immediately. Configure a webhook to be notified when it reaches a terminal state, then call GET /v1/requests/{requestId} to fetch the full result.

Batch

Submit multiple requests in one call by wrapping them in { "requests": [...] }. The response returns one entry per submitted request, in the same order. Each entry carries its own requestBatchId, and those IDs may or may not match across the batch. Within a single submission, entries scheduled for the same business day share a requestBatchId; entries scheduled for different days get distinct ones. Whether your batch lands on a single day or spills across multiple days depends on your account’s daily call capacity and any work already pending from prior submissions on those days. Always read each entry’s requestBatchId from the response. Don’t assume they match.

curl -X POST https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/requests \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
        "inputs": { "payerName": "Sample Insurance Co", "memberId": "TEST123456789", "phoneNumber": "2125551234" },
        "internalId": "claim_001"
      },
      {
        "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
        "inputs": { "payerName": "Sample Insurance Co", "memberId": "TEST987654321", "phoneNumber": "2125551234" },
        "internalId": "claim_002"
      }
    ]
  }'

Batch response

A batch responds with one entry per request, in the same order as the input. Each entry is either a success body or the uniform {error, message, [details]} envelope:

{
  "requests": [
    {
      "requestId": "8bF7xK2mP9qR4sT6uV0w",
      "requestBatchId": "pH9kJ2lM4nB6vC8xZ7Qr",
      "internalId": "claim_001"
    },
    {
      "error": "INVALID_REQUEST",
      "message": "schemaId is required"
    }
  ]
}

The HTTP status code reflects the aggregate outcome:

Status code	Meaning
`200`	All entries in the batch were created successfully.
`207`	Mixed: at least one entry succeeded and at least one failed with a client-side (4xx) error. Inspect each entry.
`400`	Either the top-level request body was invalid (e.g., `requests` was empty), OR every entry in the batch failed with a client-side error.
`500`	An internal failure occurred during batch processing. Body is either the top-level `{error: "INTERNAL_ERROR", message: "..."}` envelope (the common case) or `{"requests": [...]}` with per-entry envelopes. Check for the `requests` key to tell them apart, and treat each entry independently.

Batches don’t have to be all-or-nothing. We recommend treating each entry independently: successful entries are real, persisted requests, even if other entries in the same batch failed.

To list every request under a given requestBatchId later, for example to track progress on one day’s slice of a large batch, use GET /v1/requests?requestBatchId=.... For a multi-day batch, iterate over the unique IDs returned in the create response.

Required fields

Every request body must include:

Field	Description
`schemaId`	The schema that defines the output fields. Discover yours via `GET /v1/schemas`.
`inputs`	A JSON object of `{ key: value }` pairs. All values must be strings. The keys are schema-specific: discover required and optional ones via `GET /v1/schemas/{schemaId}/required-inputs`. Typical examples include `payerName`, `memberId`, `phoneNumber`, `providerNpi`, `dateOfService`.

requestType is server-derived from the schema: you’ll see the canonical value on the RequestResponse returned by GET /v1/requests/{requestId}. You can still send a requestType field on the POST body if existing client code does; it’s silently ignored. Required inputs.{key} fields are validated when the request is created: if any are missing or fail format checks, the request is rejected with HTTP 400 and the uniform INVALID_INPUTS error envelope:

{
  "error": "INVALID_INPUTS",
  "message": "Required inputs are missing or invalid.",
  "details": {
    "missingInputs": ["memberId", "providerNpi"],
    "invalidInputs": { "dateOfService": "must be YYYY-MM-DD" }
  }
}

details is only present on this INVALID_INPUTS path; other 400 errors carry just error + message. Discover the required inputs per schema with GET /v1/schemas/{schemaId}/required-inputs, or ask your account team. See the API Reference for POST /v1/requests for the full request body schema.

If your account is enabled for per-payer required inputs (opt-in: ask your account team), some payers require additional inputs beyond the schema’s fields, depending on payerName. A missing one is reported here in details.missingInputs like any other. Add it and retry.

Optional fields

Field	Description
`webhookUrl`	Per-request webhook URL override. Wins over the account default for this one request.
`useMatchedPayerPhone`	Boolean (default `false`). When `true` and payer phone number lookup is enabled, dial SuperDial’s matched payer number even if you supplied `phoneNumber`, falling back to your number when no match is found. Ignored when lookup is off. Goes here at the top level of the request, not inside `inputs` — see where to put the flag.
`internalId`	Optional correlation ID, and also the request’s idempotency key. Echoed on all reads and webhooks. If you supply one it must be unique per request (see below). If you omit it, SuperDial generates one for you.
`internalTag`	Opaque tag echoed on reads and webhooks (e.g. `"march-batch"`).
`aiOnly`	Boolean. When `true`, any phone call this request makes is handled only by our automated voice agent, never a human agent. Leaving it `false` adds no restriction: it doesn’t force human-agent handling. Defaults to `false`.
`onshoreOnly`	Boolean. When `true`, all phone handling for this request is restricted to US-based agents. Leaving it `false` adds no restriction. Defaults to `false`.

Correlation and idempotency

internalId is optional and serves two purposes:

Correlation: when you supply one, it’s echoed back on every read and every webhook for that request, so you can tie SuperDial results to your own records.
Idempotency: internalId is the idempotency key. A POST /v1/requests that reuses an internalId you’ve sent before does not create a new request; it returns the originally created requestId (and the original payerLookup, if any).

Because internalId is the idempotency key, a new internalId must be different on every distinct request you want to place. Reusing one is not an error and produces no warning: it silently returns the original request instead of starting new work. Use a value that’s naturally unique per request (a UUID, or your own primary key), not a constant or a reused batch label.

You don’t have to send one. internalId is optional. If you omit it, SuperDial generates and maintains its own unique idempotency key server-side, so retries are still de-duplicated for you. Supply your own only when you want to correlate results back to records on your end; otherwise leave it off and let SuperDial manage it.

// First call
POST /v1/requests  { "internalId": "claim_001", ... }
→ 200  { "requestId": "8bF7xK2mP9qR4sT6uV0w", ... }

// Retry with the SAME internalId: no new request is created
POST /v1/requests  { "internalId": "claim_001", ... }
→ 200  { "requestId": "8bF7xK2mP9qR4sT6uV0w", ... }   // same ID, no duplicate

// Omit internalId entirely: SuperDial generates its own key
POST /v1/requests  { ... }            // no internalId
→ 200  { "requestId": "aC3hN5jD8eL1fM2gK6Yo", ... }   // new request every call

internalId-based idempotency applies on a per-request basis. In batch submissions, each entry with an internalId is independently deduped: a duplicate entry returns the previously created requestId and requestBatchId rather than creating a new request. There is no batch-level idempotency key, only per-entry.

What happens after creation

The request immediately begins running through one or more modalities (electronic systems and/or phone calls). Completion time varies: electronic-only requests can finish quickly; phone-backed requests depend on payer responsiveness and hold times. Configure a webhook to be notified the moment a request finishes, then call GET /v1/requests/{requestId} to fetch the full result.

Error handling

Every non-2xx response from /v1/requests returns the same envelope:

{
  "error": "MACHINE_CODE",
  "message": "Human-readable description.",
  "details": { /* optional, only on INVALID_INPUTS */ }
}

Switch on error for programmatic dispatch; surface message to humans.

HTTP code	`error` code	Meaning	What to do
`400`	`INVALID_REQUEST`	Body wasn’t a JSON object, a required field is missing (`schemaId`, `inputs`), the batch `requests` array is empty, or scheduling capacity is exceeded. The validator’s specific reason is in `message`.	Fix the body and retry
`400`	`INVALID_INPUTS`	Input validation failed. `details.missingInputs` lists field names that weren’t supplied; `details.invalidInputs` maps field name to the reason it was rejected. With per-payer required inputs enabled, some payers add inputs that can appear here too.	Fix the inputs and retry
`400`	`PAYER_NOT_FOUND`	Payer phone number lookup path: the supplied `payerName` did not match any known payer. Only fires when lookup is enabled for your account, `payerName` is set, and `phoneNumber` is not.	Confirm spelling, try a more canonical payer name, or supply `phoneNumber` directly to skip the lookup
`401`	(gateway envelope)	Bearer token missing, malformed, or expired. Returns the gateway’s `{code, message}` shape, not the envelope above.	Fetch a fresh token via `GET /v1/auth`
`404`	`SCHEMA_NOT_FOUND`	`schemaId` doesn’t exist for your account, or has been retired. On a batch, schema-not-found surfaces per-entry as `INVALID_REQUEST` with `"Schema not found"` in `message`. Read `message` to distinguish 4xx causes when an entry has no status code.	Discover valid `schemaId` values with `GET /v1/schemas`
`404`	`ACCOUNT_NOT_FOUND`	The API key resolves to an account that no longer exists. Rare: wrong-API-key cases hit `INVALID_API_KEY` at `/v1/auth` first.	Contact support
`500`	`INTERNAL_ERROR`	Unexpected server failure. Single-item POST: body is the envelope above. Batch: body can take either shape: the top-level `INTERNAL_ERROR` envelope (most common) or `{"requests": [...]}` with per-entry envelopes (server-error entries surface here as `INVALID_REQUEST` rather than `INTERNAL_ERROR`). Check for the `requests` key to tell the two shapes apart.	Retry once; escalate if persistent
`500`	`PAYER_LOOKUP_FAILURE`	Payer phone number lookup path: the supplied `payerName` matched a payer but our database has no phone number on file, or the lookup hit a transient infra failure. Only fires when lookup is enabled for your account.	Retry with backoff, or supply `phoneNumber` directly to skip the lookup

For batch submissions, each failed entry inside the requests array carries the same envelope shape as a top-level error, so you can use the same error handler everywhere.

Get Started

Requests

Schemas

Payers

Authentication

Single request

Response

Batch

Batch response

Required fields

Optional fields

Correlation and idempotency

What happens after creation

Error handling

​Authentication

​Single request

​Response

​Batch

​Batch response

​Required fields

​Optional fields

​Correlation and idempotency

​What happens after creation

​Error handling

Authentication

Single request

Response

Batch

Batch response

Required fields

Optional fields

Correlation and idempotency

What happens after creation

Error handling