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. Each supplied value is format-checked by type (phone, date, dollar amount, boolean, regex-constrained string) and against two universal rules (no scientific notation, no curly braces); some accounts also enforce memberId structure and per-payer required inputs. Missing or format-invalid inputs return INVALID_INPUTS (400) with details.missingInputs and/or details.invalidInputs. See the Input Validation guide for the full rule list, Creating a Request for examples, and Payer Phone Number Lookup 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. When true and payer phone number lookup is enabled for your account, dial SuperDial's matched payer number even if you supplied phoneNumber, falling back to your supplied number when no match is found (no error). When omitted or false, a supplied phoneNumber is always dialed as-is. Ignored when lookup is off. See Payer Phone Number Lookup.
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 on every created request when payer phone number lookup is enabled for the account (its matched* fields are null unless SuperDial dialed its own matched number).
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. Always present on a created request when payer phone number lookup is enabled for your account. phoneNumberToUse is the number that will be dialed and phoneNumberSource says where it came from. The matched* fields are populated only when SuperDial dials its own matched number (you omitted phoneNumber, or set useMatchedPayerPhone: true and a match was found); when your supplied number is dialed they are null and phoneNumberSource is input. See the Payer Phone Number Lookup guide.