Verify API - Get started with email

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page shows you step-by-step how to use the Telesign Verify API to send an email message to an end user with a one-time passcode (OTP). It also explains how to complete the verification process, either to test the end user's asserted OTP or so you don't get charged for any unnecessary messages.

Before you can send an email message to an end user, you will need to create an email template. This page also explains step-by-step how to use Telesign Verify API to create an email template with the assistance of our Customer Support Team.

Understanding content available in email messages

You can use Verify API to send transactional emails to end users you already have permission to send emails to. Cold outreach emails and any kind of unsolicited emails are not allowed.

In addition to the text message in the body of the email, include a one-time passcode (OTP) placeholder, {{otp_code}} to designate the location of the OTP in your email message.

Your content can also include:

• Your corporate or brand logo.
• A link to a corporate or brand video.

Your content must:

• Use links for images or videos you want to include representing the logo or brand. Telesign does not host images or videos on your behalf so links to the images or videos must be publicly accessible URLs.

🚧

CAUTION:

Additional content restrictions may apply depending on the country of the sender or the recipient. See Email restrictions in compliance rules and consult with our Customer Support Team to discuss any additional restrictions on email content.

Your content may be subject to review by Telesign. Not all content is eligible to be sent via Verify API using email. You are responsible for complying with all applicable laws and are subject to all compliance rules as appropriate for your transaction.

Before you begin

Make sure you have the following before you start:

• Set up email for your account: Before sending a message using email, you first need to work with our Customer Support Team to set up email for your account. The Customer Support Team will also help you add your corporate or brand communications logo and other brand information for use with your emails.

Create your template

1. Decide what information to include in the title and message body of your new email template. You may send transactional emails to end users that you already have permission to send emails to. As noted before, cold outreach emails and any kind of unsolicited emails are not allowed.

2. Include the {{otp_code}} placeholder in the body of the text where you want the end user's unique OTP. Once your template is in place, you will be able to pass the value for a OTP in each request to the API that uses it.

3. Decide the name for the template you want to create. The template name must include only lowercase letters and underscores. For example: vero_finto_verify. Our Customer Support Team can assist you with any additional requirements for your template name or any other required content that you need to supply when you set up email in your account. You will include this template name in your API requests to select the new template.
   
   

   🚧

   CAUTION:

   The template name is specified only once in the POST request. This means that if you use fallback methods, the same template name is applied to all methods. Therefore, you need to ensure that each active channel has a template with that name. While the content can differ, the name must remain the same.

4. Contact our Customer Support Team to let them know you want to add an email template to use with Verify API. Include all the details from the steps above. We may ask additional questions or ask you to provide more details that we need for the template.

5. Once we have all necessary requirements from you, we create an email template and add it to the configuration for your account.

6. We then notify you that the email template is in place. You can begin sending requests to the Verify API using the new template. Once your email template is ready to use, follow the steps below to send an email to an end user with a one-time passcode (OTP).

Send OTP via email

📘

NOTE:

Updating a verification process using the procedure explained in Complete verification and get delivery status is a mandatory step when using Verify API. This step allows Telesign to know the real state of your verification as well as control all the features related to a verification process such as fallback, callback, and pricing. If your end user has verified themselves but the verification process is not updated, these features might not work as intended which can lead to extra costs or incorrect billing.

Keep the reference pages Create a verification process and Update a verification process open in another window while you work on these steps.

Send the request

1. Send a Create a verification process request to the Verify API. Include the following parameter values:

Your request should look similar to this request example.

Request

POST /verification HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json; charset=utf-8
Host: verify.telesign.com
{
  "recipient": {
    "email": "[email protected]",
    "phone_number": "11234567890"
  },
  "message_template": {
    "name": "verification_template"
  },
  "verification_policy": [
    {
      "method": "email",
      "fallback_time": 120
    },
    {
      "method": "sms",
      "fallback_time": 120
    }
  ]
}

2. The service then sends an email message to your end user, inserting a randomly generated OTP in the message.

3. Save the value of the property reference_id from the response. You will need it to complete the verification flow.

4. The status.code and status.description properties in the response indicate the preliminary delivery status.

   Response

   HTTP

   HTTP/1.1 200 OK
   Content-Type: application/json
   {
     "reference_id": "0123456789ABCDEF0123456789ABCDEF",
     "recipient": {
       "email": "[email protected]",
       "phone_number": "11234567890"
     },
     "state": "ONGOING",
     "verification_policy": [
       {
         "method": "email",
         "fallback_time": 120
       },
       {
         "method": "sms",
         "fallback_time": 120
       }
     ],
     "status": {
       "code": 3901,
       "description": "Request in progress"
     }
   }
   

   
   

   📘

   NOTE:

   The status.code property gives you status of delivery to the destination carrier, not necessarily all the way to the end user.

Complete verification and get delivery status

Once your end user has submitted a potential code through your application, complete the verification flow with a second API call.

1. Send an Update a verification process request to the Verify API. This is to provide Telesign with the asserted OTP from the end user.

   Parameter	Value	Description	Required?
   action	finalize	Specifies how you want to change the verification state for this verification process.	yes
   security_factor	A string consisting of a series of numeric digits.	The end user's asserted one-time passcode (OTP).	yes

Your request should look similar to this request example.

Request

PATCH /verification/0123456789ABCDEF0123456789ABCDEF/state HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json; charset=utf-8
Host: verify.telesign.com
{
  "action": "finalize",
  "security_factor": "5724433"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": {
    "code": 3900,
    "description": "Verified"
  }
}

2. If Telesign generated the OTP, and the value of the status.description property is Verified, the verification process completed successfully.