Confirm an SMS purchase quote
POST/api/v1/sms/quotes/{id}/confirm
curl -X POST 'https://www.unitpost.com/api/v1/sms/quotes/123/confirm' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'User-Agent: my-app/1.0' \
-H 'Content-Type: application/json' \
-d '{ }'{
"object": "sms_quote",
"id": "id_123",
"product": "ten_dlc_brand_registration",
"status": "open",
"label": "string",
"brand_id": "brand_123",
"registration_id": "registration_123",
"messaging_program_id": "messaging_program_123",
"country": "string",
"due_now_cents": 0,
"monthly_cents": 0,
"currency": "usd",
"line_items": [
{
"fee_code": "string",
"label": "string",
"amount_cents": 0,
"cadence": "one_time",
"starts_when": "on_confirmation"
}
],
"covered_by_unitpost": false,
"expires_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"confirmed_at": "2026-01-01T00:00:00.000Z",
"order": {
"registration_id": "registration_123",
"number_id": "number_123",
"status": "queued"
},
"confirm_token": "string"
}Buy what the quote binds, with its single-use confirm_token. It charges the workspace: confirm only after the person agreed to the quoted price. Requires an Idempotency-Key: a retry with the same key answers what the first call answered and never charges twice. The order runs exactly as in the dashboard: the plan's purchase rules, the one-time fee taken from the plan's allowance before carriers are called and refunded if they refuse the submission, the monthly fee from when the number leases or carriers approve the campaign. Every API purchase counts against the monthly API spend cap the workspace owner sets in the dashboard (the fee due now plus the first month, per UTC month); with no cap set, API purchases are refused. The owner gets an email per purchase, and the activity log names the key. Refusals charge nothing: a changed price (price_changed), an expired quote (quote_expired), a brand or messaging program edited since (quote_stale), a quote already used (quote_already_used), an order for the same purchase still in flight (conflict, naming its quote). These refusals are answered before the shared hourly limits are spent. A confirm that recorded nothing leaves the quote open (and frees its Idempotency-Key); one that reached carriers spends it: failed when carriers refused it (quote again), pending when their answer is unknown (follow the quote; don't buy the same thing meanwhile). Requires the sms:purchase capability.
Parameters2 fields
| Field | Type | Description |
|---|---|---|
idrequired | string · path | — |
Idempotency-Keyrequired | string · header | Any unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`. |
Request body1 field
| Field | Type | Description |
|---|---|---|
confirm_tokenrequired | string | The quote's confirm token (`sqct_…`), from its create response. Single use. |
Response · 200 fields19 fields
| Field | Type | Description |
|---|---|---|
objectrequired | string | — |
idrequired | string | The quote (`squote_…`). |
productrequired | enumten_dlc_brand_registration | ten_dlc_brand_vetting | ten_dlc_campaign | ten_dlc_number | long_code_number | toll_free_number | — |
statusrequired | enumopen | expired | confirming | ordered | pending | failed | `open` until confirmed or `expires_at`; `ordered` once placed; `pending` while the outcome is unknown (the carrier didn't answer: a fee due now is held, monthly fees are committed, and it settles to `ordered` or `failed` from the billing ledger, so read it again; don't buy the same thing meanwhile); `failed` when the confirm bought nothing (nothing was charged; quote again). |
labelrequired | string | What is bought, as the dashboard names it. |
brand_idrequired | string | null | — |
registration_idrequired | string | null | The registration the order is for (a brand registration, or the campaign whose number it is). |
messaging_program_idrequired | string | null | — |
countryrequired | string | null | — |
due_now_centsrequired | integer | Charged at the confirm, from the plan's allowance (one-time fees). |
monthly_centsrequired | integer | Charged when the number leases or carriers approve the campaign, then every month. |
currencyrequired | string | — |
line_itemsrequired | object[] | — |
covered_by_unitpostrequired | boolean | This workspace's carrier fees are covered by Unitpost: nothing is charged. |
expires_atrequired | string | Confirm before this (quotes last 10 minutes). |
created_atrequired | string | — |
confirmed_atrequired | string | null | — |
orderrequired | object | null | What the confirmed order made; null until then. |
confirm_token | string | Only in the create response, once: pass it to the confirm. Stored only as a hash; a lost token means a new quote. |