Templates

(new)

Verify Templates are in Public Beta!

Pre-approved and custom templates are currently in the Public Beta maturity stage, which means that:

We're actively looking for early-adopter customers to try it out and give us feedback. That could be you.

Pre-approved and custom templates are only supported with the SMS and Voice channels.

Templates are predefined and approved messages used to send Verifications that allow you to customize the Verification message. An account can have multiple templates associated with it to accommodate various scenarios.

Verify offers three different types of templates to support your use cases: Verify Default, pre-approved, and custom. Read more about the features and differences of these template types here.

Template translations and supported languages

Verify will automatically resolve a template message body's locale based on phone number country code or fallback to English or a custom template's default language. Using this automatic resolution is highly recommended. If you still must override locale, use the locale parameter. Learn more about supported languages here.

(information)

Info

To learn about special restrictions for sending SMS, consult the issues on sending to Singapore or Canada. To use a template in China, register the template with the account.

Template properties

Property nameTypeRequiredDescriptionChild properties

sidSID<HJ>

Optional

Not PII

A 34 character string that uniquely identifies a Verification Template.

Pattern: ^HJ[0-9a-fA-F]{32}$Min length: 34Max length: 34

accountSidSID<AC>

Optional

Not PII

The unique SID identifier of the Account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

friendlyNamestring

Optional

Not PII

A descriptive string that you create to describe a Template. It can be up to 32 characters long.

channelsarray[string]

Optional

Not PII

A list of channels that support the Template. Can include: sms, voice.

translationsobject

Optional

Not PII

An object that contains the different translations of the template. Every translation is identified by the language short name and contains its respective information as the approval status, text and created/modified date.

Get a list of available templates

GET https://verify.twilio.com/v2/Templates

Query parameters

Property nameTypeRequiredPIIDescription

friendlyNamestring

Optional

Not PII

String filter used to query templates with a given friendly name.

pageSizeinteger<int64>

Optional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

pageinteger

Optional

Not PII

The page index. This value is simply for client state.

Minimum: 0

pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Get a list of available templates

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listVerificationTemplate() {
11  const templates = await client.verify.v2.templates.list({ limit: 20 });
12
13  templates.forEach((t) => console.log(t.translations));
14}
15
16listVerificationTemplate();

Response

1{
2  "templates": [
3    {
4      "sid": "HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6      "friendly_name": "Base Verification Template 2 with do not share",
7      "channels": [
8        "sms"
9      ],
10      "translations": {
11        "en": {
12          "is_default_translation": true,
13          "status": "approved",
14          "locale": "en",
15          "text": "Your {{friendly_name}} verification code is: {{code}}. Do not share this code with anyone.",
16          "date_updated": "2021-07-29T20:38:28.759979905Z",
17          "date_created": "2021-07-29T20:38:28.165602325Z"
18        }
19      }
20    },
21    {
22      "sid": "HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab",
23      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24      "friendly_name": "Base Verification Template 3",
25      "channels": [
26        "sms",
27        "voice"
28      ],
29      "translations": {
30        "en": {
31          "is_default_translation": true,
32          "status": "approved",
33          "locale": "en",
34          "text": "Your verification code is: {{code}}. Do not share it.",
35          "date_updated": "2021-07-29T20:38:28.759979905Z",
36          "date_created": "2021-07-29T20:38:28.165602325Z"
37        }
38      }
39    }
40  ],
41  "meta": {
42    "page": 0,
43    "page_size": 50,
44    "first_page_url": "https://verify.twilio.com/v2/Templates?PageSize=50&Page=0",
45    "previous_page_url": null,
46    "url": "https://verify.twilio.com/v2/Templates?PageSize=50&Page=0",
47    "next_page_url": null,
48    "key": "templates"
49  }
50}

(information)

Tip

If you have jq installed you can quickly see all of the English language templates with the following command:

1curl -X GET "https://verify.twilio.com/v2/Templates" \
2  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
3  | jq '.templates[] | {sid: .sid, template: .translations.en.text}'

Set a default template for your Verify Service

To set a default template for a new Service, set the default_template_sid parameter:

Create a Service with a default template

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createService() {
11  const service = await client.verify.v2.services.create({
12    defaultTemplateSid: "HJXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13    friendlyName: "My Verify Service",
14  });
15
16  console.log(service.sid);
17}
18
19createService();

Response

1{
2  "sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "friendly_name": "My Verify Service",
5  "code_length": 4,
6  "lookup_enabled": false,
7  "psd2_enabled": false,
8  "skip_sms_to_landlines": false,
9  "dtmf_input_required": false,
10  "tts_name": "name",
11  "mailer_sid": "MDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12  "do_not_share_warning_enabled": false,
13  "custom_code_enabled": true,
14  "push": {
15    "include_date": false,
16    "apn_credential_sid": "CRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17    "fcm_credential_sid": null
18  },
19  "totp": {
20    "issuer": "test-issuer",
21    "time_step": 30,
22    "code_length": 3,
23    "skew": 2
24  },
25  "whatsapp": {
26    "msg_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27    "from": "whatsapp:+1234567890"
28  },
29  "default_template_sid": "HJXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
30  "verify_event_subscription_enabled": false,
31  "date_created": "2015-07-30T20:00:00Z",
32  "date_updated": "2015-07-30T20:00:00Z",
33  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
34  "links": {
35    "verification_checks": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/VerificationCheck",
36    "verifications": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications",
37    "rate_limits": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RateLimits",
38    "messaging_configurations": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/MessagingConfigurations",
39    "entities": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities",
40    "webhooks": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks",
41    "access_tokens": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AccessTokens"
42  }
43}

Start a Verification with a specific template

To send a verification with a specified template, include the TemplateSid (starts with HJ) as a parameter.

Start a Verification with a template

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createVerification() {
11  const verification = await client.verify.v2
12    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .verifications.create({
14      channel: "sms",
15      templateSid: "HJXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
16      to: "+15017122661",
17    });
18
19  console.log(verification.status);
20}
21
22createVerification();

Response

1{
2  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "to": "+15017122661",
6  "channel": "sms",
7  "status": "pending",
8  "valid": false,
9  "date_created": "2015-07-30T20:00:00Z",
10  "date_updated": "2015-07-30T20:00:00Z",
11  "lookup": {},
12  "amount": null,
13  "payee": null,
14  "send_code_attempts": [
15    {
16      "time": "2015-07-30T20:00:00Z",
17      "channel": "SMS",
18      "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
19    }
20  ],
21  "sna": null,
22  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
23}