SMS Verify - Screen recipients using Verify Plus

This page walks you step-by-step through how to screen out potentially fraud-related SMS Verify transactions using a Verify Plus risk score 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 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 score threshold. For more explanation of how to interpret Intelligence results, see Understanding your score and related details and the Intelligence 2.0 scale in the Intelligence documentation. The default score threshold for self-service accounts is 601. See How can I customize my risk score 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 score threshold to phone numbers of all configured countries. You can override this on a per country basis. See How can I customize my risk score 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 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 score for it. If the score exceeds the risk threshold set, the SMS is not sent.

If the score 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 score, 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 score, reason codes explaining why we gave the score 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 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 score, 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 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",  
  "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": "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

phone_type

PropertyTypeDescriptionExample
score_status.phone_type.codestringOne of the phone type codes.2
score_status.phone_type.descriptionstringText describing the phone type.MOBILE

risk

PropertyTypeDescriptionExampleValidations
score_status.riskobjectContains properties related to the risk score for the specified phone number.
score_status.risk.recommendationstringThe action that Telesign recommends that you take based on the risk score.allowScore Scales provides a table with risk levels.
score_status.risk.scoreintegerThe risk score for the current transaction.601Between 1 and 1000.
score_status.risk.levelstringThe severity of the risk.highScore scales provides a table with risk levels.

risk_insights

PropertyTypeDescriptionExample
score_status.risk_insightsobjectContains reason code properties with additional information related to the risk score.
score_status.risk_insights.statusintegerThe processing status of the risk insights package for the request.800
score_status.risk_insights.categoryarray of integersReason codes related to the category of the phone number, as described in Intelligence - Insights reason code mappings10010
score_status.risk_insights.a2parray of integersReason codes specific to application-to-person communication (A2P), as described in Intelligence - Insights reason code mappings. These are automated communications sent to a human, like verification codes, appointment reminders, etc.22103, 20011, 20101
score_status.risk_insights.p2parray of integersReason codes specific to person-to-person communication (P2P), as described in Intelligence - Insights reason code mappings. This is two-way communication between two humans, like one friend texting another.30201
score_status.risk_insights.number_typearray of integersReason codes related to the phone number’s type, as described in Intelligence - Insights reason code mappings.
score_status.risk_insights.iparray of integersReason codes related to activity of the IP you provided for the phone number, as described in Intelligence - Insights reason code mappings.
score_status.risk_insights.emailarray of integersReason codes related to activity of the email address you provided for the phone number, as described in Intelligence - Insights reason code mappings.

numbering

PropertyTypeDescriptionExample
score_status.numberingobjectContains properties related to the numbering attributes of the specified phone number.
score_status.numbering.phone_numberstringThe base phone number. This is the phone number without the country dialing code.1234567890
score_status.numbering.min_lengthintegerThe minimum number of digits allowed for phone numbers with this country dialing code10
score_status.numbering.max_lengthintegerThe maximum number of digits allowed for phone numbers with this country dialing code.10
score_status.numbering.country_codestringA 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 United Kingdom is 44.1