TeleSign Developer Center

Welcome! This resource hub provides documentation and references on API & SDK integration and other product-related information.

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Enterprise SMS Verify API

The SMS Verify API delivers phone-based verification and two-factor authentication (2FA) using a time-based, one-time passcode (TOTP) sent over SMS.

READ THIS NOTE:

This documentation is intended for you if you use the Enterprise versions of TeleSign products.

You use Enterprise TeleSign products if you log in to your account at teleportal.telesign.com, use endpoints that begin with rest-ww.telesign.com, and have a designated Technical Account Manager (TAM).

If you log in to your account at portal.telesign.com, are using TeleSign's free trial, have endpoints that begin with rest-api.telesign.com, and do NOT have a TAM, you need the Standard API Docs.

Before getting started, make sure to review the following pages:

The SMS Verify product includes the Verify SMS web service, which sends a verification code to your end user in a text message.

The Verify SMS web service is discussed in the following sections:

URI

To use the Verify SMS web service, send a POST request to the following URI.
https://rest-ww.telesign.com/v1/verify/sms

NOTE:

If you are using rest.telesign.com endpoints, TeleSign recommends that you upgrade to the new base URI (rest-ww.telesign.com as soon as possible). It is faster.

Verifying the Code

There are two options to generate the verification code; either you or TeleSign can generate it:

You generate the verification code

Send a POST request with the verify_code parameter set to a code you generate:

phone_number=15555551234
&ucid=TRVF
&originating_ip=203.0.113.45
&language=en-US
&verify_code=9876543
&template=Your code is $$CODE$$

Because you know the code that was sent to the end user, you can verify whether the value the end user enters is correct.

TeleSign generates the verification code

When you send a POST request without specifying a verification code, TeleSign generates the code value by default and sends it to the end user. For example:

phone_number=15555551234
&ucid=TRVF
&originating_ip=203.0.113.45
&language=en-US
&template=Your code is $$CODE$$

You then need to check whether the code that the user entered matches the one that TeleSign generated. After you receive the code that the user entered, send a GET request with verify_code as an input parameter set to the value the user entered. For example, if the code entered was 57244, your GET request would be as follows:

GET https://rest-ww.telesign.com/v1/verify/AEBC93B5898342F790E4E19FED41A7DA?verify_code=57244 HTTP/1.1

For more information, see Verifying a TeleSign-Generated Verification Code.

Obtain Verification Results / Send Completion Data

If you implemented your configuration so that TeleSign generates your codes, then you must send TeleSign completion data using a Get Status request. If you generate your own codes, sending completion data is optional, but recommended. (Completion data is the reference ID associated with an end user's transaction, and the verification code entered by the end user. This information is used by TeleSign to determine the outcome of transactions.)

Verification results are then made available to you using the verification method you select, either:

Supported HTTP Methods

POST

  • When you send a POST request with the user’s phone number to the sms subresource, the TeleSign Phone Verify service sends a text message that communicates a verification code to the phone number in the request (typically, this is the phone number your user submitted). The user is supposed to enter this code on your website, to complete their phone verification procedure.

    The URI for a POST request is /v1/verify/sms.

GET

  • After you’ve made your verification request, you can retrieve the verification results by sending a GET request to the verify resource, with a reference to your original service request for the Subresource Identifier. TeleSign returns a response message that contains the verification results in the form of a verify JSON object in the entity body.

    The URI for a GET request is /v1/verify/[reference_id].

HEAD

  • Although supported, use of the HEAD method is limited to testing because the response message returned from the web server does not contain an entity-body.

Requests

Headers

This section provides a summary of required and optional headers for a request. For details about how to use them for proper authentication, review the Authentication page. For more details about these headers, review the section Standard and TeleSign Specific Headers on the Authentication (REST) page.

General Headers

  • Content-Type - Required for POST requests. Ignored for GET requests, but you must mark its position with a newline for StringToSign.
  • Date - Required unless you include X-TS-Date. If you do not include the Date header value, you must mark its position with a newline character for StringToSign.

Request Headers

TeleSign-Specific HTTP Headers

  • X-TS-Date - Optional, you may use this instead of the Date header.
  • X-TS-Nonce - Optional, specifies a unique, random nonce string. You can include this header to provide additional protection against malicious replay attacks
  • X-TS-Auth-Method - Required for HMAC-SHA256.

Request Parameters

POST

The following parameters are supported in the body of a POST request:

phone_number

  • [Required] Your end user’s phone number, including the country code.
  • [Example] phone_number=13105551212

ucid

  • [Optional] A string that specifies one of the use case codes.
  • [Example] ucid=TRVF

originating_ip

  • [Optional] Your end user’s IP Address (do not send your own IP address). IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Internet Protocol. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled IP Version 6 Addressing Architecture.
  • [Example IPv4] originating_ip=203.0.113.45
  • [Example IPv6] originating_ip=2001:db8:85a3::8a2e:370:7334

language

  • [Optional] The IETF language tag used in applying predefined templates. For a complete list of language tags, see the section Supported Languages for Messages on the Codes, Languages, and Time Zones page.
  • [Example] language=fr-CA
  • [Default] en-US

verify_code

  • [Optional] The verification code used for the code challenge. This is a randomly-generated numeric value. By default, TeleSign automatically generates a seven digit value for you. If you use this method, you must perform a Get Status request to validate the verify_code entered by the end user. For more information about making a Get Status request, refer to the section Use Get Status to Share Completion Data on the Get Status / Verify Transaction (REST) page.
  • If you prefer to use your own verification code, you can override the default behavior by including this parameter and giving it a numeric value between 000 and 9999999.
  • [Example] verify_code=719650
  • [Default] null

NOTE:

If you submit a template message in the template parameter, or if you already have a template text message registered with TeleSign, the value of verify_code replaces the token $$CODE$$ in the template.

template

  • [Optional] A text message that overrides the predefined text message templates. Your text message must incorporate a $$CODE$$ placeholder to integrate the verify_code field. The standard message is a maximum of 160 characters, however if you want to send long messages, you can contact your Technical Account Manager to have this feature enabled. A long message may be up to 1600 characters or 2000 code points, however TeleSign recommends that you keep your messages brief when possible.

  • [Example] template=Your code is $$CODE$$

NOTE:

You must take character coding into consideration when creating your message, so that it can be easily localized into foreign languages. Contact TeleSign Technical Support with any questions or concerns.

num_deac_req

  • [Optional] To use this parameter, you must have the Number Deactivation service enabled. Contact your Technical Account Manager. This parameter can be true or false, specifying whether a number deactivation check will be done for the destination number. By default it is set to true, specifying that a number deactivation check be done. If this parameter is set to anything other than true, it is interpreted as false.

  • [Example] &num_deac_req=true

  • [Default] true

last_valid_activity_time

  • [Optional] To use this parameter, you must have the Number Deactivation service enabled. Contact your Technical Account Manager. This parameter is an RFC 1123 time stamp indicating when the last valid activity of the end user was recorded on your application or server. If this parameter is not set, it is interpreted to mean that this phone number did not have any valid action in the past.

  • [Example] &last_valid_activity_time="2012-04-17T22:26:43.784963Z"
  • [Default] null

deactivation_lookup_window

  • [Optional] To use this parameter, you must have the Number Deactivation service enabled. Contact your Technical Account Manager. This parameter specifies the window of time in which the TeleSign system will look for the Number Deactivation event. The value is the number of days preceding the Verify SMS request that defines the window of time to examine. If this parameter is not set, the value from the you should be applied. If you do not set this parameter, the default value of 0 will be used.

  • [Example] &deactivation_lookup_window=30

  • [Default] 0

number_deactivation_action

  • [Optional] To use this parameter, you must have the Number Deactivation service enabled. Contact your Technical Account Manager. This parameter can have the values block or flag. block specifies that an SMS request not be sent if there is a Number Deactivation event and all required conditions are met. If you do not set this parameter, the default value is block. flag specifies that an SMS always be sent.

  • [Example] &number_deactivation_action=flag

  • [Default] block

sender_id

  • [Optional] This parameter allows you to set a specific Sender ID to be used on an SMS message sent to the end user. Although this parameter is available, there are certain things that you need to be aware of:
    • In order to use a specific SenderID, TeleSign will have to whitelist the SenderID values and enable the functionality. Please contact the Support Team or your Technical Account Manager for further instructions.
    • Preservation of the Sender ID value is not 100% guaranteed. TeleSign may override the Sender ID value that your end user will receive in order to improve delivery quality and/or follow SMS regulations in particular countries.

GET

No parameters are supported in a GET request. Instead, use the reference_id as the Subresource Identifier in your GET request.

reference_id

  • [Required] The reference identifier that TeleSign generated and returned in its response to your verify/sms web service request. This value uniquely identifies each TeleSign web service request.

  • [Example] https://rest-ww.telesign.com/v1/verify/ABCDEF0123456789ABCDEF0123456789

NOTE:

If you supply a verification code when you POST your service request to Verify SMS, and if the end user enters it back into your web application, then you do not need to contact TeleSign to get the verification result because you already have the two codes.

Responses

This section details the response message returned by the Verify SMS web service.

Response Headers

The TeleSign server returns the following header fields for this subresource:

Allow

  • Indicates the HTTP methods that the resource supports. The allowed methods for verify/sms are GET, POST, and HEAD.

Content-Type

  • Specifies the media type of the response message’s payload (that is, of the data contained in the response message’s entity-body). TeleSign web services always return results in the application/json data format.

Response Body

Sending a POST request to the SMS subresource returns the following response:

{
   "reference_id" : "ABCDEF0123456789ABCDEF0123456789",
   "resource_uri" : "/v1/verify/ABCDEF0123456789ABCDEF0123456789",
   "sub_resource" : "sms",
   "errors": [],
   "status" : {
      "updated_on" : "2015-04-17T22:26:43.784963Z",
      "code" : 290,
      "description" : "Message in progress"
   },
   "verify" : {
      "code_state" : "UNKNOWN",
      "code_entered" : ""
   },
   "number_deactivation_status" : {
      "error_code" : "0",
      "description" : "Number Deactivation check succeeded",
      "last_deactivated" : "2015-02-02T10:41:55.464231Z"
   },
   "additional_info": {
      "code_entered": null,
      "message_parts_count" : 1
   }
}

The response body contains a JSON object with the following members:

NOTE:

Unless otherwise specified, a missing or unspecified value defaults to null.

reference_id

  • A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response message immediately following the web service request.

resource_uri

  • The URI that accesses the verify resource. The URI is /v1/verify/[reference_id].

sub_resource

  • The subresource to access; it is set to sms.

errors

  • A JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair is returned for each error.
    ValueDescription
    codeA 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
    descriptionA string that describes the type of error that occurred.
    If no errors occur, then this array is empty. "errors": []

status

    An object that describes the verification status; it contains the following parameters:
    code description
    • A text description corresponding to the verification status code.
    updated_on
    • An RFC 3339 timestamp indicating when the verification status was updated.

verify

    An object that describes the verification status; it contains the following parameters:
    code_state
    • Indicates whether the verification code entered matches that which was sent. Possible values are VALID, INVALID, and UNKNOWN. When the code entered matches the code sent, the response will be VALID. When the code entered does not match the code sent, code_state will be INVALID.
    code_entered
    • Always set to an empty string.

number_deactivation_status

    [Optional] This object contains parameters describing the status of the Number Deactivation check:
    error_code
    • [Optional] This parameter can have one of the values described in the following table:
      ValueDescriptionNotes
      0Number Deactivation check succeededThe Number Deactivation check was successful.
      -40010Phone number out of coverageThe Number Deactivation check was not done because the number is associated with a country that is not in coverage.
      -90001Number Deactivation service unavailableThe Number Deactivation check was not done for internal reasons; the request was handled as a Verify SMS request.
    description
    • [Optional] Text describing the error resulting from the Number Deactivation check, if any, as listed in the error_code table.
    last_deactivated
    • [Optional] This parameter only has a value if a Number Deactivation check was done for the MSISDN. Its value is an RFC 3339 timestamp when the phone number was seen and/or reported as deactivated from the data stream provider. If there was no number deactivation event, this value is null.

additional_info

  • The additional_info feature contains details about pricing (if enabled) and how many parts a message is broken into.

    mcc

    • Mobile Country Code (MCC) of the destination number. Returned if you request this feature from your Technical Account Manager.

    mnc

    • Mobile Network Code (MNC) of the destination number. Returned if you request this feature from your Technical Account Manager.

    price

    • The price of the message you are sending. Returned if you request this feature from your Technical Account Manager.

    message_parts_count

    • You can only get this in a response if you use Verify Transaction Callback to retrieve message status information. This parameter will display the number of parts your message was split into. If the message is not split, this returns a value of 1.

Responses When You Enable Score

If you choose to enable Score with SMS Verify, you will be able to assess a phone number's risk level for fraud (referred to as the phone number's score) prior to sending an SMS verification message. If a phone number's score is too high for the threshhold you select (work with your Technical Account Manager to set this), you can block it.

You can find out more about Score on the following pages:

An example response when Score is enabled would look like this:

{
   "reference_id" : "ABCDEF0123456789ABCDEF0123456789",
   "resource_uri" : "/v1/verify/ABCDEF0123456789ABCDEF0123456789",
   "sub_resource" : "sms",
   "errors": [],
   "status" : {
      "updated_on" : "2015-04-17T22:26:43.784963Z",
      "code" : 290,
      "description" : "Message in progress"
   },
   "verify" : {
      "code_state" : "UNKNOWN",
      "code_entered" : ""
   },
   "phone_type" : {
      "code": "2",
      "description": "MOBILE"
   },
   "risk" : {
   		"recommendation"; "allow",
      "score": 1,
      "level": "low"
   },
   "numbering" : {
   		"phone_number": "5558675309",
      "min_length": 10,
      "max_length": 10,
      "country_code": "1"
   }   
   "number_deactivation_status" : {
      "error_code" : "0",
      "description" : "Number Deactivation check succeeded",
      "last_deactivated" : "2015-02-02T10:41:55.464231Z"
   }
}

With Score enabled, the response you receive will have the same information as the regular SMS Verify response, plus the following additional parameters. They are:

numbering

  • ValueDescription
    country_code A 1, 2, or 3-digit number representing the country dialing code. For example, the country dialing code for both the U.S.A. and Canada is 1, and the country dialing code for the United Kingdom is 44.
    max_length The maximum number of digits allowed for phone numbers with this particular country dialing code.
    min_length The minimum number of digits allowed for phone numbers with this particular country dialing code.
    phone_number The base phone number. This is simply the phone number without the country dialing code.

phone_type

  • An object containing details about the phone type. This object contains the following parameters:
    Value Description
    code One of the phone type codes
    description Text describing the phone type

risk

  • An object that describes the risk score for the phone number specified in the request; it contains the following parameters:
    Value Description
    level A string indicating the severity of the risk.
    recommendation A string indicating the action that TeleSign recommends that you take based on the risk score
    score One of the scores and risk levels values

Examples

The following examples demonstrate typical HTTP 1.1 Request/Response transactions for invoking the Verify SMS web service, and for retrieving the verification results.

Invoking the Web Service

Request

You invoke the web service by sending a POST request message like this one, to the TeleSign web server.

POST https://rest-ww.telesign.com/v1/verify/sms HTTP/1.1
Accept-Encoding: gzip,deflate
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: ca10235f-f41a-4c54-baf1-1bd808f7404f
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Wed, 03 Oct 2015 14:51:26 -0700
Content-Type: application/x-www-form-urlencoded; charset=utf-8
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com
Content-Length: 59

phone_number=15555551234
   &ucid=TRVF
   &originating_ip=203.0.113.45
   &language=en-US
   &verify_code=9876543

NOTE:

The Request parameters are shown on separate lines for illustration purposes.

Response

TeleSign returns the following message in response to the preceding example request.

HTTP/1.1 200 OK
Date: Wed, 03 Oct 2015 14:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 316
Allow: GET,POST,HEAD
Content-Type: application/json
{
   "reference_id": "0123456789ABCDEF0123456789ABCDEF",
   "resource_uri": "/v1/verify/0123456789ABCDEF0123456789ABCDEF",
   "sub_resource": "sms",
   "errors": [],
   "status": {
      "updated_on": "2015-10-03T14:51:28.709526Z",
      "code": 290,
      "description": "Message in progress"
    },
    "verify": {
       "code_state": "UNKNOWN",
       "code_entered": ""
    },
    "additional_info": {
      "message_parts_count" : 1
    }
}

Retrieving Verification Results

You retrieve the verification results by sending a GET request message to the TeleSign web server.

Request

You use the reference_id of the Verify SMS service request as the subresource identifier.

GET https://rest-ww.telesign.com/v1/verify/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Accept-Encoding: gzip,deflate
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: 4b33a3af-fd87-421d-b494-dafdc36b0b00
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Date: Wed, 03 Oct 2015 14:53:11 GMT
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com

Response

TeleSign returns the following message in response to the preceding example request.

HTTP/1.1 200 OK
Date: Wed, 29 May 2015 00:09:08 UTC
Server: CERN/3.0 libwww/2.17
Content-Length: 314
Allow: GET,POST,HEAD
Content-Type: application/json
{
   "reference_id" : "ABCDEF0123456789ABCDEF0123456789",
   "resource_uri" : "/v1/verify/ABCDEF0123456789ABCDEF0123456789",
   "sub_resource" : "sms",
   "errors": [],
   "status" : {
      "updated_on" : "2015-05-29T00:09:08.784963Z",
      "code" : 1190,
      "description" : "Transaction in progress"
   },
   "user_response" : {
      "received" : null,
      "verification_code" : null,
      "selection" : null
   }
}

Callback Service Verification Results

The following example illustrates the JSON objects delivered by the TeleSign Verify Transaction Callback service.

HTTP/1.1 200 OK
Date: Wed, 06 Nov 2015 13:35:40 -0800
Server: CERN/3.0 libwww/2.17
Content-Length: 296
Allow: GET
Content-Type: application/json
{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "submit_timestamp": "Wed, 06 Nov 2015 13:36:07 -0800",
  "sub_resource": "sms",
  "errors":[],
  "status": {
     "updated_on": "Wed, 06 Nov 2015 13:36:11 -0800",
     "code": 290,
     "description": "Message in progress"
  },
  "verify": {
     "code_entered": null,
     "code_state": "UNKNOWN"
  }
}

Verifying a TeleSign-Generated Verification Code

Request

When TeleSign generates the value of the verification code, you can check whether the code that the user entered matches the one that TeleSign generated. To do this, send a GET request with verify_code as an input parameter, and set it to the value the user entered. For example, if the code entered was 57244, you would make the GET request as follows:

GET https://rest-ww.telesign.com/v1/verify/AEBC93B5898342F790E4E19FED41A7DA?verify_code=57244 HTTP/1.1

Response

If the code that you sent in the GET request matches the TeleSign-generated code, the value of code_state will be 'valid' in the response:

{
   "reference_id" : "AEBC93B5898342F790E4E19FED41A7DA",
   "resource_uri" : "/v1/verify/AEBC93B5898342F790E4E19FED41A7DA",
   "sub_resource" : "sms",
   "errors": [],
   "status" : {
      "updated_on" : "2015-04-17T22:26:43.784963Z",
      "code" : 290,
      "description" : "Message in progress"
   },
   "verify" : {
      "code_state" : "valid",
      "code_entered" : "57244"
   }
}

URL Shortener

To help shorten your text messages, TeleSign provides a complimentary URL shortening service. You can read more about how to enable it here: URL Shortener for Enterprise.

SMS Status Codes

This table lists the status codes (and the associated strings) returned in response to an Verify SMS service request.

Status Code
Associated Text String
Description

200

Delivered to handset

SMS has been delivered to the user’s phone.

203

Delivered to gateway

SMS has been delivered to the gateway. If the gateway responds with further information (including successful delivery to handset or delivery failure), the status is updated.

207

Error delivering SMS to handset (reason unknown)

SMS could not be delivered to the user’s handset for an unknown reason.

210

Temporary phone error

SMS could not be delivered to the handset, due to a temporary error with the phone. For example, the phone is turned off, or there is not enough memory to store the message.

211

Permanent phone error

SMS could not be delivered to the handset, due to a permanent error with the phone. For example, the phone is incompatible with SMS or is illegally registered on the network. This happens when a phone number is blacklisted or incorrectly provisioned.

220

Gateway/network cannot route message

Network cannot route the message to the handset.

221

Message expired before delivery

The message was queued by the mobile provider and timed out before it could be delivered to the handset.

222

SMS not supported

SMS is not supported by this phone, carrier, plan, or user.

229

Message blocked by your request

TeleSign blocked the SMS before it was sent. This is due to your prior submitted request to blocklist this phone number.

230

Message blocked by TeleSign

TeleSign blocked the SMS before it was sent. This can happen if the message contains spam or inappropriate material or if TeleSign believes the client is abusing the account in any way.

231

Invalid/unsupported message content

The content of the message is not supported.

232

Message blocked due to number deactivation event

It was determined that the destination number was found and/or reported as deactivated from the data stream provider. This number deactivation event occurred within the deactivation lookup window, and after the last valid activity of the end user was recorded on your side.

233

Message blocked due to high risk score.

It was determined that the risk score for the destination number is higher than configured Maximum Risk Score. For that reason TeleSign did not send the SMS.

250

Final status unknown

The final status of the message cannot be determined.

251

Message successfully sent out for delivery, however final confirmation of delivery to handset was not received.

The message was sent for delivery, but there was no confirmation of receipt.

290

Message in progress

The message is being sent to the SMS gateway.

291

Queued by TeleSign

TeleSign is experiencing unusually high volume and has queued the SMS message.

292

Queued at gateway

The SMS gateway has queued the message.

295

Status delayed

The status of the SMS is temporarily unavailable.

500

Transaction not attempted

No Call, SMS, or PhoneID request was attempted.

501

Not authorized

No permissions for this resource, or authorization failed.

502

Campaign error

There is a problem with the short code used.

503

Carrier rejected - temporary problem

A temporary error on the carrier or operator side. The message can be retried.

504

Carrier rejected - permanent error

A permanent error on the carrier or operator side. The message should not be retried.

505

Error on gateway - temporary error

A temporary error on TeleSign’s partner side. The message can be retried.

506

Error on gateway - permanent error

A permanent error on TeleSign’s partner side. The message should not be retried.

507

Invalid destination address

There is a problem with destination address used. The format is not valid, or the number is not associated with a carrier, or the MSC used does not know about the MSISDN.

508

Invalid source address

The message requires a source address, verify one is provided, and is correct.

509

Parameters problem

One or more parameters used in the request is not supported.

510

Message blocked by subscriber action or request

End user has blocked receiving SMS by this carrier plan, or the request or the short code used is blocked.

511

Subscriber low on credit

End user has exceeded their spending limit, and therefore cannot receive SMS.

512

Roaming error

End user cannot receive SMS while roaming.

513

Mobile number portability error

SMS failed because ported combinations are unreachable.

514

Subscriber absent

Subscriber is absent for a period of time.

515

Suspected spam

This message is considered as spam by the carrier or operator.

599

Status not available

The system is unable to provide a status at this time.

Enterprise SMS Verify API