Docs
BetaSDKsGet startedTalk to salesSign inSupportStatusPricing

SMS Verify API - Screen recipients using Verify Plus

This page walks you step-by-step through how to screen out potentially fraud-related SMS Verify API transactions using a Verify Plus risk recommendation before sending them a verification SMS. The Verify Plus add-on is powered by a separate product, Telesign Intelligence.

You can do this all directly through the SMS Verify API, without using the Detect API. This is more efficient than making an additional call to the Detect API.

Keep the reference pages POST /v1/verify/sms and GET /v1/verify/{reference_id} open in another window while you work through these steps.

Before you begin

  • Upgrade your account: Upgrade to a paid account if you are using a trial account.
  • "From" phone number: You must buy a “from” phone number from Telesign before sending OTPs to any number other than the one you registered your account with.
  • Activate Verify Plus: See our support article How can I activate the Verify Plus add-on? for more details on how to activate this add-on. Verify Plus is available for all account types (including trial accounts).

📘

NOTE:

Once Verify Plus is activated for your account, all requests to phone numbers of your configured countries are evaluated by Verify Plus.

Configure Verify Plus

  1. Decide on a default risk recommendation threshold. For more explanation of how to interpret Intelligence results, see Understanding a risk recommendation for a phone number. The default risk recommendation threshold for self-service accounts is 601. See How can I customize my risk recommendation threshold for Verify Plus? for more details.
  2. Decide if you want to exclude any countries from Verify Plus checks or use it for all transactions. To customize which countries are evaluated by Verify Plus see the support article Can I customize which countries Verify Plus covers?.
  3. Decide if you want to set any country-specific thresholds. By default, Verify Plus applies one default recommendation threshold to phone numbers of all configured countries. You can override this on a per country basis. See How can I customize my risk recommendation threshold for Verify Plus? for more details.

Send the SMS

Once Verify Plus is activated, follow these steps.

  1. Make an HTTP request to Telesign by sending a POST /verify/sms request to the SMS Verify API. Include the following parameter values:

    ParameterValueDescriptionRequired?
    phone_numberDigits without spaces or special characters.The end user’s phone number you want to send a message to, beginning with the country/dialing code.yes
    templateText with a variable.Text that overrides the contents of the predefined message templates. Include the $$CODE$$ variable to have the verification code automatically inserted.no

    It should look this:

    POST /v1/verify/sms HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: rest-ww.telesign.com
phone_number=1234567890
&language=en-US
&template=Your code is $$CODE$$

    If your request is successful, you should get an HTTP response that says "Message in progress":

    HTTP/1.1 200 OK  
Content-Type: application/json  
{  
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",  
  "sub_resource": "sms",  
  "errors": [],  
  "status": {  
    "updated_on": "2022-04-17T22:26:43.784963Z",  
    "code": 290,  
    "description": "Message in progress"  
  }  
}

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

📘

NOTE:

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

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

The phone number of the recipient included in the phone_number parameter is passed on to Intelligence for evaluation. Intelligence analyzes risk signals associated with the phone number and calculates a risk recommendation for it. If the risk recommendation exceeds the risk threshold set, the SMS is not sent.

If the risk recommendation doesn't exceed the risk threshold set, Telesign generates an OTP, replaces $$CODE$$ in the message text, and sends the SMS message to the phone number.

Process your callback

  1. Search transactions sent to your Transaction Callback Service to find one that matches the Reference ID you saved from the original HTTP response. Telesign sends a DLR callback (SMS Verify Callbacks) to your callback service to report either:

    • the sending of the SMS was blocked due to high risk recommendation, or
    • the SMS was delivered to the handset for that phone number.

  2. (Optional) Create reporting, if desired, based on the percentage of callbacks blocked or allowed. You might also choose to break down the block rate by country. The callback includes extra Verify Plus related properties, including not only whether the send was blocked or allowed, but also its exact risk recommendation, reason codes explaining why we gave the risk recommendation that we did, and other details associated with the phone number. These properties are contained in the packages risk, risk_insights, phone_type, and numbering.

    Example callbacks

    SMS Verify API Callback: Not blocked

    POST /callback_endpoint HTTP/1.1  
Host: your-callback-url.com  
{
  "status": {
    "code": 200,
    "description": "Delivered to handset",
    "updated_on": "2022-04-17T14:05:36.181346Z"
  },
  "submit_timestamp": "2022-04-17T01:01:01.010101Z",
  "errors": [],
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": null
  },
  "sub_resource": "sms",
  "additional_info": {
    "message_parts_count": 2,
    "price": "0.5112",
    "mnc": "004",
    "mcc": "310",
    "currency": "USD",
    "message_parts_reference_ids": "35E63E88CB000E049196AD1CFCFFB89C,35E63E88CC7C050491613443467F3F12"
  },
  "score_status": {
    "phone_type": {
      "code": "2",
      "description": "MOBILE"
    },
    "risk": {
      "recommendation": "allow",
      "score": 82,
      "level": "low"
    },
    "risk_insights": {
      "status": 800,
      "category": [
        10010
      ],
      "a2p": [
        22103,
        20011,
        20101
      ],
      "p2p": [
        30201
      ],
      "number_type": [],
      "ip": [],
      "email": []
    },
    "numbering": {
      "phone_number": "1234567890",
      "min_length": 10,
      "max_length": 10,
      "country_code": "1"
    }
  }
}

If the verification message is not sent due to a high risk recommendation, the property status.code in the response has a value of 233, and you are not charged for the SMS transaction (though you are still charged for Intelligence). If the SMS was blocked, the verification flow ends at this point.

SMS Verify API Callback: Blocked

POST /callback_endpoint HTTP/1.1  
Host: your-callback-url.com  
{
  "status": {
    "code": 233,
    "description": "Message blocked due to high risk score",
    "updated_on": "2022-04-17T14:05:36.181346Z"
  },
  "submit_timestamp": "2022-04-17T01:01:01.010101Z",
  "errors": [],
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": null
  },
  "sub_resource": "sms",
  "score_status": {
    "phone_type": {
      "code": "2",
      "description": "MOBILE"
    },
    "risk": {
      "recommendation": "block",
      "score": 700,
      "level": "high"
    },
    "risk_insights": {
      "status": 800,
      "category": [
        10010
      ],
      "a2p": [
        22103,
        20011,
        20101
      ],
      "p2p": [
        30201
      ],
      "number_type": [],
      "ip": [],
      "email": []
    },
    "numbering": {
      "phone_number": "1234567890",
      "min_length": 10,
      "max_length": 10,
      "country_code": "1"
    }
  }
}

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 a GET /verify/{reference_id} HTTP request.

    • Include the end-user's potential code in the verify_code query parameter.
    • Include the reference_id for the transaction in the reference_id path parameter. This is the same reference_id that you saved earlier.

    Get status request 

    GET /v1/verify/0123456789ABCDEF0123456789ABCDEF?verify_code=57244 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com

  2. Telesign compares the end-user's potential code to the OTP generated by Telesign and in the HTTP response tells you if there was a valid match or not. If the value of the verify.code_state property is VALID, the verification completed successfully.

    HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "updated_on": "2022-04-17T22:26:43.784963Z",
    "code": 200,
    "description": "Delivered to handset"
  },
  "verify": {
    "code_state": "VALID",
    "code_entered": ""
  },
  "additional_info": {
    "code_entered": null,
    "message_parts_count": 1
  }
}

  3. If the value of the verify.code_state property is EXPIRED or MAX_ATTEMPTS_EXCEEDED, the verification code is no longer matchable by your end user. If you still want to give them the opportunity to verify, make a new SMS Verify request to send them a new verification code.

Intelligence package schemas

The intelligence package schema can be found on the Receive SMS Verify Callbacks reference page.

Updated about 2 months ago

© 2024 Telesign / Terms & Conditions / Privacy Notice / Privacy Hub