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

# SuperDial API

> Submit requests and retrieve results programmatically.

`POST /v1/requests` submits a [**request**](/guides/concepts#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`](/guides/schemas).

<Note>
  Looking for the legacy SuperDial docs? They're still available at [superdial.readme.io](https://superdial.readme.io/).
</Note>

## 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](/guides/concepts#production-vs-sandbox) for which key to use when.

## Quickstart

The end-to-end flow has four steps:

<Steps>
  <Step title="Authenticate">
    Exchange your API key and secret for a 1-hour bearer token at [`GET /v1/auth`](/guides/creating-a-request#authentication).
  </Step>

  <Step title="Submit a request">
    [`POST /v1/requests`](/guides/creating-a-request) with `schemaId` and `inputs`. Optionally pass `internalId` for correlation and idempotency.
  </Step>

  <Step title="Wait for completion">
    SuperDial fires a [webhook](/guides/webhooks) to your configured URL when the request reaches a terminal state (`SUCCESS`, `PARTIAL`, or `FAILURE`).
  </Step>

  <Step title="Fetch the result">
    [`GET /v1/requests/{requestId}`](/guides/reading-requests#single-request) returns the structured `results`. When a phone call was placed, the response also includes the call transcript, recording URL, and summary.
  </Step>
</Steps>

Test the full flow without placing real phone calls using the [Sandbox](/guides/sandbox).

## Where to start

<CardGroup cols={2}>
  <Card title="Concepts & Glossary" href="/guides/concepts">
    Definitions for request, schema, payer, state, error object, modality, and other terms used throughout the API.
  </Card>

  <Card title="Sandbox" href="/guides/sandbox">
    Test your integration end-to-end without placing real phone calls. What's identical to production, what's mocked.
  </Card>

  <Card title="Creating a Request" href="/guides/creating-a-request">
    How to submit a single request or a batch with `POST /v1/requests`. Required fields, idempotency, batch semantics.
  </Card>

  <Card title="Reading Requests" href="/guides/reading-requests">
    Fetch a request by ID, list requests by date, or pull all requests in a batch.
  </Card>

  <Card title="Webhooks" href="/guides/webhooks">
    Receive request results when they reach a terminal state. Payload shape, signature verification, retry behavior.
  </Card>

  <Card title="Schemas" href="/guides/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.
  </Card>

  <Card title="Payer Phone Number Lookup" href="/guides/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.
  </Card>
</CardGroup>

## API Reference

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