Create a Request
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.
Authorizations
Bearer token obtained from the /v1/auth endpoint
Body
- Option 1
- Option 2
Schema ID. Discover yours via GET /v1/schemas.
Inputs as a flat { key: value } object — every value must be a string. The required and optional keys are schema-specific; discover them with GET /v1/schemas/{schemaId}/required-inputs. Missing or format-invalid required inputs return INVALID_INPUTS (400). See the Creating a Request guide for examples, and Payer Resolution for how omitting phoneNumber affects the response.
Optional and ignored. Historical field; the request type is derived server-side from the schema. You'll see the canonical value on the requestType field of the RequestResponse returned by GET /v1/requests/{requestId}.
Optional. Per-request webhook URL override. Wins over the account-level webhook URL for this single request.
Optional correlation ID that also serves as the request's idempotency key. A retry with the same internalId does not create a new request — it returns the original requestId and the original payerLookup (if any), even if our payer data has changed since. Because it is the idempotency key, a value you supply must be unique per distinct request; reusing one silently returns the original request instead of starting new work. If you omit it, SuperDial generates and maintains its own unique key server-side, so you only need to supply one when you want to correlate results to your own records. See the Correlation and idempotency section in the Creating a Request guide.
Optional. Customer tag, echoed back on reads and webhooks. Useful for grouping requests without polluting your correlation IDs.
Optional. When true, any phone call this request makes is handled only by our automated (AI) voice agent, never a human agent. Leaving it false adds no restriction — it does not force human-agent handling. Defaults to false.
Optional. When true, all phone handling for this request is restricted to US-based agents. Leaving it false adds no restriction. Defaults to false.
Response
Request(s) created successfully. The body is CreateRequestSuccess for a single-item POST and CreateRequestBatchResponse (with every entry a success) for a batch.
- Option 1
- Option 2
Success response from POST /v1/requests on a single-item POST. internalId is echoed only when supplied in the body. payerLookup is present only when the account has payer-phone resolution enabled AND the request supplied inputs.payerName without inputs.phoneNumber.
Server-generated request ID. Stable across idempotent retries with the same internalId. Use it on GET /v1/requests/{requestId} to fetch the full result.
Server-generated batch ID this request belongs to.
Optional. Echoed back from the request body if you supplied one.
Payer-phone lookup outcome, returned on POST /v1/requests success responses and on the GET /v1/requests read endpoints. Only present when the request supplied (or matched) a payer name — see the Payer Resolution guide for when that happens. The resolved phone number is intentionally omitted: dialing happens server-side and is never echoed to clients. Compare inputPayerName against matchedPayerName to confirm the right payer was matched.