Skip to main content
POST /v1/requests submits a request by specifying a schemaId and inputs. A schema defines both the inputs it requires and the fields you’ll get back in results. GET /v1/requests/{requestId} returns the structured result. Discover the schemas provisioned for your account with GET /v1/schemas.
Looking for the legacy SuperDial docs? They’re still available at superdial.readme.io.

​
Authentication

Every endpoint other than GET /v1/auth requires a bearer token. Exchange your API key and secret at GET /v1/auth for a short-lived token, then pass it as Authorization: Bearer <token> on every subsequent call (POST/GET /v1/requests, GET /v1/requests/{requestId}, GET /v1/schemas, GET /v1/schemas/{schemaId}/required-inputs). See Concepts → Production vs Sandbox for which key to use when.

​
Quickstart

The end-to-end flow has four steps:
1

Authenticate

Exchange your API key and secret for a 1-hour bearer token at GET /v1/auth.
2

Submit a request

POST /v1/requests with schemaId and inputs. Optionally pass internalId for correlation and idempotency.
3

Wait for completion

SuperDial fires a webhook to your configured URL when the request reaches a terminal state (SUCCESS, PARTIAL, or FAILURE).
4

Fetch the result

GET /v1/requests/{requestId} returns the structured results. When a phone call was placed, the response also includes the call transcript, recording URL, and summary.
Test the full flow without placing real phone calls using the Sandbox.

​
Where to start

Concepts & Glossary

Definitions for request, schema, payer, state, error object, modality, and other terms used throughout the API.

Sandbox

Test your integration end-to-end without placing real phone calls. What’s identical to production, what’s mocked.

Creating a Request

How to submit a single request or a batch with POST /v1/requests. Required fields, idempotency, batch semantics.

Reading Requests

Fetch a request by ID, list requests by date, or pull all requests in a batch.

Webhooks

Receive request results when they reach a terminal state. Payload shape, signature verification, retry behavior.

Schemas

Discover the schemas provisioned for your account and the input keys each one requires, so you can submit requests without checking with your account team first.

Payer Resolution

How payerName resolves to a canonical payer record and dialing phone number — when it runs, what shapes the answer, and how to handle each failure mode.

​
API Reference

The API Reference tab has the full endpoint specifications, request/response shapes, and every error code with examples.