Create a new Verification using a Service

POST /v2/Services/{ServiceSid}/Verifications
Account sid auth token

Create a new Verification using a Service

Path parameters

  • ServiceSid string Required

    The SID of the verification Service to create the resource under.

    Minimum length is 34, maximum length is 34. Format should match the following pattern: ^VA[0-9a-fA-F]{32}$.

application/x-www-form-urlencoded

Body

  • To string Required

    The phone number or email to verify. Phone numbers must be in E.164 format.

  • Channel string Required

    The verification method to use. One of: email, sms, whatsapp, call, sna or auto.

  • CustomFriendlyName string

    A custom user defined friendly name that overwrites the existing one in the verification message

  • CustomMessage string

    The text of a custom message to use for the verification.

  • SendDigits string

    The digits to send after a phone call is answered, for example, to dial an extension. For more information, see the Programmable Voice documentation of sendDigits.

  • Locale string

    Locale will automatically resolve based on phone number country code for SMS, WhatsApp, and call channel verifications. It will fallback to English or the template’s default translation if the selected translation is not available. This parameter will override the automatic locale resolution. See supported languages and more information here.

  • CustomCode string

    A pre-generated code to use for verification. The code can be between 4 and 10 characters, inclusive.

  • Amount string

    The amount of the associated PSD2 compliant transaction. Requires the PSD2 Service flag enabled.

  • Payee string

    The payee of the associated PSD2 compliant transaction. Requires the PSD2 Service flag enabled.

  • RateLimits

    The custom key-value pairs of Programmable Rate Limits. Keys correspond to unique_name fields defined when creating your Rate Limit. Associated value pairs represent values in the request that you are rate limiting on. You may include multiple Rate Limit values in each request.

  • ChannelConfiguration

    email channel configuration in json format. The fields 'from' and 'from_name' are optional but if included the 'from' field must have a valid email address.

  • AppHash string

    Your App Hash to be appended at the end of your verification SMS body. Applies only to SMS. Example SMS body: <#> Your AppName verification code is: 1234 He42w354ol9.

  • TemplateSid string

    The message template. If provided, will override the default template for the Service. SMS and Voice channels only.

    Minimum length is 34, maximum length is 34. Format should match the following pattern: ^HJ[0-9a-fA-F]{32}$.

  • TemplateCustomSubstitutions string

    A stringified JSON object in which the keys are the template's special variables and the values are the variables substitutions.

  • DeviceIp string

    Strongly encouraged if using the auto channel. The IP address of the client's device. If provided, it has to be a valid IPv4 or IPv6 address.

  • EnableSnaClientToken boolean

    An optional Boolean value to indicate the requirement of sna client token in the SNA URL invocation response for added security. This token must match in the Verification Check request to confirm phone number verification.

  • RiskCheck string

    Values are enable or disable.

  • Tags string

    A string containing a JSON map of key value pairs of tags to be recorded as metadata for the message. The object may contain up to 10 tags. Keys and values can each be up to 128 characters in length.

Responses

  • 201 application/json

    Created

    Hide headers attributes Show headers attributes
    • Retry-After string
    • Twilio-Reached-Rate-Limit string
    • Access-Control-Allow-Origin string

      Specify the origin(s) allowed to access the resource

    • Access-Control-Allow-Methods string

      Specify the HTTP methods allowed when accessing the resource

    • Access-Control-Allow-Headers string

      Specify the headers allowed when accessing the resource

    • Access-Control-Allow-Credentials boolean

      Indicates whether the browser should include credentials

    • Access-Control-Expose-Headers string

      Headers exposed to the client

    Hide response attributes Show response attributes object
    • sid string | null

      The unique string that we created to identify the Verification resource.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^VE[0-9a-fA-F]{32}$.

    • service_sid string | null

      The SID of the Service the resource is associated with.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^VA[0-9a-fA-F]{32}$.

    • account_sid string | null

      The SID of the Account that created the Verification resource.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • to string | null

      The phone number or email being verified. Phone numbers must be in E.164 format.

    • channel string

      The verification method used. One of: email, sms, whatsapp, call, sna, or rcs.

      Values are sms, call, email, whatsapp, or sna.

    • status string | null

      The status of the verification. Can be: pending, approved, canceled, max_attempts_reached, deleted, failed or expired.

    • valid boolean | null

      Use "status" instead. Legacy property indicating whether the verification was successful.

    • lookup

      Information about the phone number being verified.

    • amount string | null

      The amount of the associated PSD2 compliant transaction. Requires the PSD2 Service flag enabled.

    • payee string | null

      The payee of the associated PSD2 compliant transaction. Requires the PSD2 Service flag enabled.

    • send_code_attempts array | null

      An array of verification attempt objects containing the channel attempted and the channel-specific transaction SID.

    • date_created string(date-time) | null

      The date and time in GMT when the resource was created specified in RFC 2822 format.

    • date_updated string(date-time) | null

      The date and time in GMT when the resource was last updated specified in RFC 2822 format.

    • sna

      The set of fields used for a silent network auth (sna) verification. Contains a single field with the URL to be invoked to verify the phone number.

    • url string(uri) | null

      The absolute URL of the Verification resource.
POST /v2/Services/{ServiceSid}/Verifications 
curl \
 --request POST 'https://verify.twilio.com/v2/Services/{ServiceSid}/Verifications' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data 'To=%2B15017122661&Tags=%7B%22tenant_id%22%3A+%2212345%22%7D&Payee=Acme+Inc.&Amount=%E2%82%AC39.99&Locale=en&AppHash=AAAAAAAAAAA&Channel=sms&RiskCheck=enable&CustomCode=custom_code&SendDigits=ww1&TemplateSid=HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&CustomMessage=custom_message&CustomFriendlyName=custom_friendly_name&TemplateCustomSubstitutions=%7B%22AppName%22%3A+%22MyApp%22%2C+%22Contact%22%3A%2212345689%22%7D'
Request examples 
{"To"=>"+15017122661", "Tags"=>"{\"tenant_id\": \"12345\"}", "Payee"=>"Acme Inc.", "Amount"=>"€39.99", "Locale"=>"en", "AppHash"=>"AAAAAAAAAAA", "Channel"=>"sms", "RiskCheck"=>"enable", "CustomCode"=>"custom_code", "SendDigits"=>"ww1", "TemplateSid"=>"HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "CustomMessage"=>"custom_message", "CustomFriendlyName"=>"custom_friendly_name", "TemplateCustomSubstitutions"=>"{\"AppName\": \"MyApp\", \"Contact\":\"12345689\"}"}
{"To"=>"+15017122661", "Locale"=>"en", "Channel"=>"whatsapp", "CustomCode"=>"custom_code", "CustomFriendlyName"=>"custom_friendly_name"}
{"To"=>"mail@email.com", "Payee"=>"Acme Inc.", "Amount"=>"€39.99", "Locale"=>"en", "Channel"=>"email", "CustomCode"=>"custom_code", "CustomMessage"=>"custom_message", "ChannelConfiguration"=>"{\"from\": \"foo@bar.com\", \"from_name\": \"Bar Inc.\", \"substitutions\": { \"username\": \"ms. baz\" }, \"template_id\": \"Dxxxxxxxxxx\"}"}
{"To"=>"+15017122661", "Locale"=>"en", "Channel"=>"sms", "CustomCode"=>"custom_code", "RateLimits"=>"{\"my_rate_limit_key\": \"abc\"}", "SendDigits"=>"ww1", "CustomMessage"=>"custom_message"}
{"To"=>"+15017122661", "Channel"=>"sna"}
{"To"=>"+15017122661", "Channel"=>"auto", "DeviceIp"=>"0.000.00.000"}
Response examples (201) 
{
  "to": "+15017122661",
  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sna": null,
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "payee": null,
  "valid": false,
  "amount": null,
  "lookup": {},
  "status": "pending",
  "channel": "sms",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "send_code_attempts": [
    {
      "time": "2015-07-30T20:00:00Z",
      "channel": "SMS",
      "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}
{
  "to": "+15017122661",
  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sna": null,
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "payee": null,
  "valid": false,
  "amount": null,
  "lookup": {},
  "status": "pending",
  "channel": "whatsapp",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "send_code_attempts": [
    {
      "time": "2015-07-30T20:00:00Z",
      "channel": "whatsapp",
      "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}
{
  "to": "mail@email.com",
  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sna": null,
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "payee": null,
  "valid": false,
  "amount": null,
  "lookup": {},
  "status": "pending",
  "channel": "email",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "send_code_attempts": [
    {
      "time": "2015-07-30T20:00:00Z",
      "channel": "EMAIL",
      "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}
{
  "to": "+15017122661",
  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sna": null,
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "payee": null,
  "valid": false,
  "amount": null,
  "lookup": {},
  "status": "pending",
  "channel": "sms",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "send_code_attempts": [
    {
      "time": "2015-07-30T20:00:00Z",
      "channel": "SMS",
      "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}
{
  "to": "+15017122661",
  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sna": {
    "url": "https://mi.dnlsrv.com/m/id/ANBByzx7?data=AAAglRRdNn02iTFWfDWwdTjOzM8o%2F6JB86fH%2Bt%2FFftUPj0pFA0u8%2FibWuYwzmMeMOtdTwYlsO8V%2FXF%2BJmngMhbeGKYhHeTOF2H9VrGEYKcEEklPxHgb5GgL3XtYa33j3lIU%2By6InvoV%2FowWHBzA0QeFPBh6vmJ8LoUPJqGE7q0PRz618Z4ym1AGq%2BaomSq9PlP4rCduv9Cmtxu%2FrvPSBwocs0GCWDE8seK8t9epmPQW7gwODxkAiKr9UxhJd9KvmBVuAQPf%2BoFQVo86USXkhXqTvUzB2bNUYY9FCy3CWgZFTOa1D3H1CVxf1eHzYIswNA7SmOzP%2FBX8g6%2B0hkzwMRkcit3gBNs4evAVJiqAgYvUlrtGwwv9bFx4X7jWSHY4%3D&cipherSalt=yANeDq09bwM38SJs"
  },
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "payee": null,
  "valid": false,
  "amount": null,
  "lookup": {
    "carrier": {
      "name": "T-Mobile USA, Inc.",
      "type": "mobile",
      "error_code": null,
      "mobile_country_code": "311",
      "mobile_network_code": "180"
    }
  },
  "status": "pending",
  "channel": "sna",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "send_code_attempts": [
    {
      "time": "2015-07-30T20:00:00Z",
      "channel": "sna",
      "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}
{
  "to": "+15017122661",
  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sna": {
    "url": "https://mi.dnlsrv.com/m/id/ANBByzx7?data=AAAglRRdNn02iTFWfDWwdTjOzM8o%2F6JB86fH%2Bt%2FFftUPj0pFA0u8%2FibWuYwzmMeMOtdTwYlsO8V%2FXF%2BJmngMhbeGKYhHeTOF2H9VrGEYKcEEklPxHgb5GgL3XtYa33j3lIU%2By6InvoV%2FowWHBzA0QeFPBh6vmJ8LoUPJqGE7q0PRz618Z4ym1AGq%2BaomSq9PlP4rCduv9Cmtxu%2FrvPSBwocs0GCWDE8seK8t9epmPQW7gwODxkAiKr9UxhJd9KvmBVuAQPf%2BoFQVo86USXkhXqTvUzB2bNUYY9FCy3CWgZFTOa1D3H1CVxf1eHzYIswNA7SmOzP%2FBX8g6%2B0hkzwMRkcit3gBNs4evAVJiqAgYvUlrtGwwv9bFx4X7jWSHY4%3D&cipherSalt=yANeDq09bwM38SJs"
  },
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "payee": null,
  "valid": false,
  "amount": null,
  "lookup": {
    "carrier": {
      "name": "T-Mobile USA, Inc.",
      "type": "mobile",
      "error_code": null,
      "mobile_country_code": "311",
      "mobile_network_code": "180"
    }
  },
  "status": "pending",
  "channel": "sna",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "send_code_attempts": [
    {
      "time": "2015-07-30T20:00:00Z",
      "channel": "sna",
      "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}