Confirm an SMS purchase quote

Confirm an SMS purchase quote

POST/api/v1/sms/quotes/{id}/confirm

POST /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 '{ }'
Response · 200
{
  "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
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keyrequiredstring · headerAny 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
FieldTypeDescription
confirm_tokenrequiredstringThe quote's confirm token (`sqct_…`), from its create response. Single use.
Response · 200 fields19 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThe quote (`squote_…`).
productrequiredenumten_dlc_brand_registration | ten_dlc_brand_vetting | ten_dlc_campaign | ten_dlc_number | long_code_number | toll_free_number—
statusrequiredenumopen | 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).
labelrequiredstringWhat is bought, as the dashboard names it.
brand_idrequiredstring | null—
registration_idrequiredstring | nullThe registration the order is for (a brand registration, or the campaign whose number it is).
messaging_program_idrequiredstring | null—
countryrequiredstring | null—
due_now_centsrequiredintegerCharged at the confirm, from the plan's allowance (one-time fees).
monthly_centsrequiredintegerCharged when the number leases or carriers approve the campaign, then every month.
currencyrequiredstring—
line_itemsrequiredobject[]—
covered_by_unitpostrequiredbooleanThis workspace's carrier fees are covered by Unitpost: nothing is charged.
expires_atrequiredstringConfirm before this (quotes last 10 minutes).
created_atrequiredstring—
confirmed_atrequiredstring | null—
orderrequiredobject | nullWhat the confirmed order made; null until then.
confirm_tokenstringOnly in the create response, once: pass it to the confirm. Stored only as a hash; a lost token means a new quote.
200400401402403404409422429500502

Search docs and guides

Search the docs and product guides.