Verify - Templates API Reference

You use custom templates to modify the default messages sent by the Verify API. You can even add messages in currently unsupported languages.

By default Verify messages conform to the following templates:

{
  "lg": "en-us",
  "template": "${brand} code: ${pin}. Valid for ${pin_expiry} minutes."
}
{
  "lg": "en-gb",
  "template": "<break time='1s'\/> Please enter your ${brand} activation code ${pin}, I repeat ${pin}, valid the next ${pin_expiry} minutes."
}

Nexmo inserts a random ${pin} into template. The brand and pin_expiry parameters in your call to Verify Request fill ${brand} and ${pin_expiry} in the template.

You use a custom template to create a fully branded experience for your user. You completely manage the text, variables and audio streams.

A custom template looks like:

{
  "action_type": "voice",
  "lg": "en_ie",
  "contact_email" : "xyz@example.com",   
  "template": "this is the template. with a ${pin}",
  "welcome_message": "https://example.com/welcome.wav",
  "digit_0": "https://example.com/message_zero.wav",
  "digit_1": "https://example.com/message_one.wav",
  "digit_2": "https://example.com/message_two.wav",
  "digit_3": "https://example.com/message_three.wav",
  "digit_4": "https://example.com/message_four.wav",
  "digit_5": "https://example.com/message_five.wav",
  "digit_6": "https://example.com/message_six.wav",
  "digit_7": "https://example.com/message_seven.wav",
  "digit_8": "https://example.com/message_eight.wav",
  "digit_9": "https://example.com/message_nine.wav",
  "bye_message": "https://example.com/bye.wav"
}
{
  "action_type" : "sms",
  "lg" : "ru-ru",
  "type" : "unicode",
  "contact_email" : "xyz@example.com",
  "template" : "Ваш код подтверждения ${pin}"
}
{
  "action_type": "voice",
  "lg": "ja-jp",
  "contact_email" : "xyz@example.com",
  "template": "あなたの ${brand}コードは ${pin} です。 繰り返します。 あなたの ${brand}コードは ${pin} です。"
}

Note: you do not use the type parameter for Voice custom templates.

To setup custom templates:

#!/bin/bash

#Connection information
base_url='https://api.nexmo.com'
version=''
action='/verify/templates'

#Authentication information
api_key='API_KEY'
api_secret='API_SECRET'

#Create the request URL
url="${base_url}${version}${action}?api_key=${api_key}&api_secret=${api_secret}"

#Create the custom template
payload='{
  "action_type" : "sms",
  "lg" : "en-gb",
  "contact_email" : "xyz@example.com",
  "template" : "Your ${brand} verification code is ${pin}"
}'

curl -X POST $url \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d "$payload"
<?php

//Connection information
$base_url = 'https://api.nexmo.com' ;
$version = '';
$action = '/verify/templates';

//Authentication information
$api_key = 'API_KEY';
$api_secret = 'API_SECRET';

//Create the request URL
$url = $base_url . $version . $action . "?api_key=" . $api_key . "&api_secret=" . $api_secret;

//Set the headers
$headers =  array('Content-Type: application/json', 'Accept: application/json') ;

//Create the payload for an SMS custom template
$payload = '{
  "action_type" : "sms",
  "lg" : "en-gb",
  "contact_email" : "xyz@example.com",
  "template" : "Your ${brand} verification code is ${pin}"
}';

//Create the request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);

echo $response;
import json
import requests

#Connection information
base_url = 'https://api.nexmo.com'
version = ''
action = '/verify/templates'

#Authentication information
api_key = 'API_KEY'
api_secret = 'API_SECRET'

#Create the request URL
url = base_url + version + action + "?api_key=" + api_key + "&api_secret=" + api_secret

#Set the headers
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

#Change the to parameter to the number you want to call
payload = {
  "action_type" : "sms",
  "lg" : "en-gb",
  "contact_email" : "xyz@example.com",
  "template" : "Your ${brand} verification code is ${pin}"
}

response = requests.post( url , data=json.dumps(payload), headers=headers)

if (response.status_code == 201):
    print response.content
else:
    print( "Error: " + str(response.status_code) + " " +    response.content)
require "net/http"
require "uri"
require "json"

#Connection information
base_url = 'https://api.nexmo.com'
version = ''
action = '/verify/templates'

#Authentication information
api_key = 'API_KEY'
api_secret = 'API_SECRET'

#Create the request URL
url = base_url + version + action + "?api_key=" + api_key + "&api_secret=" + api_secret

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

#Change the to parameter to the number you want to call
payload = {
  "action_type" => "sms",
  "lg" => "en-gb",
  "contact_email" => "xyz@example.com",
  "template" => "Your ${brand} verification code is ${pin}"
}.to_json

uri = URI( url )

req = Net::HTTP::Post.new(uri.request_uri, headers)
req.body = payload

response = Net::HTTP.start(uri.host, uri.port,
        :use_ssl => uri.scheme == 'https') {|http| http.request req}

case response
when Net::HTTPSuccess
  puts "success" +  response.body
else
  puts "Error" + response.body
end

Create a custom template

The following code examples show you how to register a custom template:

#!/bin/bash

#Connection information
base_url='https://api.nexmo.com'
version=''
action='/verify/templates'

#Authentication information
api_key='API_KEY'
api_secret='API_SECRET'

#Create the request URL
url="${base_url}${version}${action}?api_key=${api_key}&api_secret=${api_secret}"

#Create the custom template
payload='{
  "action_type" : "sms",
  "lg" : "en-gb",
  "contact_email" : "xyz@example.com",
  "template" : "Your ${brand} verification code is ${pin}"
}'

curl -X POST $url \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d "$payload"
<?php

//Connection information
$base_url = 'https://api.nexmo.com' ;
$version = '';
$action = '/verify/templates';

//Authentication information
$api_key = 'API_KEY';
$api_secret = 'API_SECRET';

//Create the request URL
$url = $base_url . $version . $action . "?api_key=" . $api_key . "&api_secret=" . $api_secret;

//Set the headers
$headers =  array('Content-Type: application/json', 'Accept: application/json') ;

//Create the payload for an SMS custom template
$payload = '{
  "action_type" : "sms",
  "lg" : "en-gb",
  "contact_email" : "xyz@example.com",
  "template" : "Your ${brand} verification code is ${pin}"
}';

//Create the request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);

echo $response;
import json
import requests

#Connection information
base_url = 'https://api.nexmo.com'
version = ''
action = '/verify/templates'

#Authentication information
api_key = 'API_KEY'
api_secret = 'API_SECRET'

#Create the request URL
url = base_url + version + action + "?api_key=" + api_key + "&api_secret=" + api_secret

#Set the headers
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

#Change the to parameter to the number you want to call
payload = {
  "action_type" : "sms",
  "lg" : "en-gb",
  "contact_email" : "xyz@example.com",
  "template" : "Your ${brand} verification code is ${pin}"
}

response = requests.post( url , data=json.dumps(payload), headers=headers)

if (response.status_code == 201):
    print response.content
else:
    print( "Error: " + str(response.status_code) + " " +    response.content)
require "net/http"
require "uri"
require "json"

#Connection information
base_url = 'https://api.nexmo.com'
version = ''
action = '/verify/templates'

#Authentication information
api_key = 'API_KEY'
api_secret = 'API_SECRET'

#Create the request URL
url = base_url + version + action + "?api_key=" + api_key + "&api_secret=" + api_secret

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

#Change the to parameter to the number you want to call
payload = {
  "action_type" => "sms",
  "lg" => "en-gb",
  "contact_email" => "xyz@example.com",
  "template" => "Your ${brand} verification code is ${pin}"
}.to_json

uri = URI( url )

req = Net::HTTP::Post.new(uri.request_uri, headers)
req.body = payload

response = Net::HTTP.start(uri.host, uri.port,
        :use_ssl => uri.scheme == 'https') {|http| http.request req}

case response
when Net::HTTPSuccess
  puts "success" +  response.body
else
  puts "Error" + response.body
end

This request contains:

Information about the Call is sent to you in the:

Base URL

All requests to manage custom templates must contain:

Payload

The payload to create a new custom template looks like:

{
  "action_type": "voice",
  "lg": "en_ie",
  "contact_email" : "xyz@example.com",   
  "template": "this is the template. with a ${pin}",
  "welcome_message": "https://example.com/welcome.wav",
  "digit_0": "https://example.com/message_zero.wav",
  "digit_1": "https://example.com/message_one.wav",
  "digit_2": "https://example.com/message_two.wav",
  "digit_3": "https://example.com/message_three.wav",
  "digit_4": "https://example.com/message_four.wav",
  "digit_5": "https://example.com/message_five.wav",
  "digit_6": "https://example.com/message_six.wav",
  "digit_7": "https://example.com/message_seven.wav",
  "digit_8": "https://example.com/message_eight.wav",
  "digit_9": "https://example.com/message_nine.wav",
  "bye_message": "https://example.com/bye.wav"
}
{
  "action_type" : "sms",
  "lg" : "en-gb",
  "Type" : "text",
  "contact_email" : "xyz@example.com",   
  "template" : "${pin} is your ${brand} verification code."
}
{
  "action_type": "voice",
  "lg": "ja-jp",
  "contact_email" : "xyz@example.com",
  "template": "あなたの ${brand}コードは ${pin} です。 繰り返します。 あなたの ${brand}コードは ${pin} です。"
}

The following table shows the parameters you use to create a custom template:

Parameter Description Required
action_type Possible values are: sms - send a text message or voice - send a text-to-speech message Yes
lg Explicitly control the language, accent and gender used to deliver the message in your custom template. For example, en-in is a female voice that delivers your message in English with an Indian accent. Calls to Verify Request for a custom template must use the same lg.
For templates in an custom locale such as en-ie, you must supply links to recorded files in your template.
yes
template The content displayed in the text message or spoken to your user in a text-to-speech call. For example: Your ${brand} download code ${pin} is valid for the next ${pin_expiry} minutes. You must set the custom template variables in calls to Verify Request.
If you set action_type to voice and specify a template, it is used in a text-to-speech call. Do not specify digit_n, welcome_message or bye_message.
No
type The encoding used for template. Possible values are: unicode or text No
digit_n URL to the media file played when digit n (0-9) is touched on the user's handset. If you specify digit_n, you must set welcome_message or bye_message. Nexmo inserts a PIN between welcome_message and bye_message. No
welcome_message URL to the media file played at the start of the call. If you set digit_n
bye_message URL to the media file played at the end of the call. If you set digit_n
contact_email Set the email address used to generate a Zendesk ticket and activate your custom template. If you do not set this parameter, the email address associated to your Master API key is used. No

Response

The JSON response looks like:

{
    "account_id": "xxxxxxxx",
    "action_type": "sms",
    "lg": "en-gb",
    "version": 2,
    "status": "pending",
    "template": "${pin} is your ${brand} verification code.",
    "type": "text"
}
{
   "account_id": "xxxxxxxx",
   "action_type": "voice",
   "bye_message": "8114bd6c-2208-432b-a46e-0880465a8fbe",
   "digit_0": "8114bd6c-2208-432b-a46e-0880465a8fbe",
   "digit_1": "01d6cb89-424f-4525-828c-504e77c7d6d4",
   "digit_2": "4a90f626-093a-4663-9778-bcd90b1e98f2",
   "digit_3": "798f836e-7395-4d08-824f-af237f18954b",
   "digit_4": "b0edd7fa-0404-4512-a8a1-c1a0c47d3100",
   "digit_5": "de4b8a27-52ff-47be-8e44-8df6c7d669a6",
   "digit_6": "c33a9ef5-19c5-436e-b93c-09b32f7e87e9",
   "digit_7": "44242673-acbd-4351-a0fc-470f4d7b38e2",
   "digit_8": "03b16135-cf60-4ee1-b2a4-41ad897fba67",
   "digit_9": "71c451f4-fb0c-4dbc-b8cb-d7ad11becdce",
   "lg": "es-es",
   "status": "pending",
   "template": "this is the template. with a ${pin}",
   "type": "text",
   "version": 19,
   "welcome_message": "8114bd6c-2208-432b-a46e-0880465a8fbe"
}

The response headers has one of the following HTTP status codes:

The response body contains the following keys and values:

Key Value
account_id Your api_key.
action_type Possible values are: sms - an sms template was used or voice - a voice template was used
bye_message The ID for the media file played at the end of the call.
digit_n The IDs for the media files used for each digit.
lg The template locale.
status Possible values are: ACTIVE - this template is currently in us, PENDING - waiting to be approved and activated or RETIRED - no longer active
template The message sent to your user in an SMS or a text-to-speech Call.
type The encoding used for template when action_type is SMS. Possible values are: unicode or text (default)
version The version number for this custom template. This number is generated automatically.
welcome_message The ID for the media file played at the start of the call.