Skip to content
Sendblue Docs
Get Started
API Reference
Verify
Verifications

Create a verification

POST/api/v2/verify/services/{service_sid}/verifications

Creates an inverted-OTP verification for the supplied E.164 phone number. The user must send the returned code from that exact phone number to the returned Sendblue destination number.

Include hosted to create an origin-bound Hosted Verify widget session. Sendblue API credentials must remain on the customer’s backend; only the returned hosted values may be sent to the browser. Twilio-compatible clients may alternatively send the API Key ID and API Secret Key with HTTP Basic authentication. Temporary bearer authentication is supported for account-scoped tokens; line-scoped temporary tokens cannot create account-wide Verifications.

Path ParametersExpand Collapse
service_sid: string
Body ParametersJSONExpand Collapse
to: string

E.164 phone number that must send the verification message.

hosted: optional object { parent_origin, accent_color, brand_name, theme }

Options for an origin-bound Hosted Verify widget session. Nested keys are strict snake_case. parent_origin must be an exact HTTPS origin with a DNS hostname. 127.0.0.1 is also accepted, and HTTP is allowed only for localhost or 127.0.0.1 development origins. Wildcards and other IP literals are rejected because browsers cannot enforce them as exact CSP frame-ancestors sources.

parent_origin: string

Exact website origin allowed to embed the widget, with no path, query, or fragment.

formaturi
maxLength2048
accent_color: optional string

Six-digit hexadecimal accent color.

brand_name: optional string

Brand name displayed by the widget. Defaults to Sendblue.

minLength1
maxLength60
theme: optional "light" or "dark" or "auto"
One of the following:
"light"
"dark"
"auto"
ReturnsExpand Collapse
account_sid: string
channel: "imessage"
date_created: string
date_updated: string
expires_at: string

ISO timestamp when the Verification expires.

formatdate-time
service_sid: string
sid: string
status: "pending" or "approved" or "expired" or "canceled"
One of the following:
"pending"
"approved"
"expired"
"canceled"
to: string

Expected sender in E.164 format; older durable terminal records may return null.

url: string
delivery_target: optional DeliveryTarget { code, pool_number, sms_deep_link }

Present while the Verification is pending.

code: string

Code the expected sender must text to pool_number.

minLength4
maxLength8
pool_number: string

Sendblue phone number that should receive the verification code.

Messages/SMS deep link with the destination and code prefilled.

hosted: optional HostedVerification { component_script, expires_at, session_id, url }

Present only when hosted options were supplied during creation.

component_script: string

Web-component script URL. Load this value exactly as returned.

formaturi
expires_at: string

ISO timestamp when the Verification expires.

formatdate-time
session_id: string

Hosted widget session identifier.

url: string

Origin-bound widget URL containing a one-session bearer token in its fragment. Do not log, persist, or move the token into a query parameter.

formaturi

Create a verification

curl https://api.sendblue.co/api/v2/verify/services/$SERVICE_SID/verifications \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "to": "+14155551212"
        }'
{
  "account_sid": "account_sid",
  "channel": "imessage",
  "date_created": "2019-12-27T18:11:19.117Z",
  "date_updated": "2019-12-27T18:11:19.117Z",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "service_sid": "SVE1CB97d8EBbDbaAae6d9B1ca0D1cFaAD",
  "sid": "VRE1CB97d8EBbDbaAae6d9B1ca0D1cFaAD",
  "status": "pending",
  "to": "+14155551212",
  "url": "https://example.com",
  "delivery_target": {
    "code": "CB6DJ9",
    "pool_number": "+17865640246",
    "sms_deep_link": "sms:+17865640246?body=CB6DJ9"
  },
  "hosted": {
    "component_script": "https://api.sendblue.co/api/v2/verify/widget.js",
    "expires_at": "2019-12-27T18:11:19.117Z",
    "session_id": "session_id",
    "url": "https://api.sendblue.co/api/v2/verify/widget?session=abc123#token=secret"
  }
}
Returns Examples
{
  "account_sid": "account_sid",
  "channel": "imessage",
  "date_created": "2019-12-27T18:11:19.117Z",
  "date_updated": "2019-12-27T18:11:19.117Z",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "service_sid": "SVE1CB97d8EBbDbaAae6d9B1ca0D1cFaAD",
  "sid": "VRE1CB97d8EBbDbaAae6d9B1ca0D1cFaAD",
  "status": "pending",
  "to": "+14155551212",
  "url": "https://example.com",
  "delivery_target": {
    "code": "CB6DJ9",
    "pool_number": "+17865640246",
    "sms_deep_link": "sms:+17865640246?body=CB6DJ9"
  },
  "hosted": {
    "component_script": "https://api.sendblue.co/api/v2/verify/widget.js",
    "expires_at": "2019-12-27T18:11:19.117Z",
    "session_id": "session_id",
    "url": "https://api.sendblue.co/api/v2/verify/widget?session=abc123#token=secret"
  }
}