Skip to main content

Quickstart for Telnyx Verify

In this tutorial, you’ll learn how to deliver a 2FA token to any mobile number and verify that token using the Telnyx v2 API and the curl command.

Portal setup​

Follow the setup guide to configure your Portal for sending and receiving messages.

Development environment setup​

Check out the Get Started Now guide to acquire your API Key.

You can paste the below snippets into your Terminal on Mac and Linux computers. Windows users should install bash on Windows or use the WLS .

Methods of verification​

There are currently three verification methods available.

  • sms, the verification code is sent in a custom or default templated message
  • call, the code is spoken aloud in a custom or default templated message when the user answers the call
  • flashcall, the phone number of the caller is used as the verification code

Step 1: Create a verify profile​

A Verify Profile contains several important configurations that you'll use when sending 2-factor authentication messages and receiving responses. Before you send any 2FA messages, you need a profile to go with them.

Each profile can have one of each verification method configured. It is recommended that if you wish to configure multiple applications, you use a different profile for each one.

In the below example we will set up a verification profile that can use SMS using a selected message template and speech to text calling.

Select a message template​

curl --location --request GET 'https://api.telnyx.com/v2/verify_profiles/templates' \
--header 'Authorization: Bearer <KEY>'

Example Response​

{
    "data": [
        {
            "id": "0abb5b4f-459f-445a-bfcd-488998b7572d",
            "text": "Your {{app_name}} verification code is: {{code}}."
        },
        {
            "id": "2ca3f1da-5621-4aa6-ae56-df21caff79e0",
            "text": "{{code}} is your verification code for {{app_name}}."
        },
        {
            "id": "33dfb056-6c1b-40bd-920e-4243e01248a5",
            "text": "Your {{app_name}} verification code is: {{code}}. Do not share this code with anyone; our employees will never ask for the code."
        },
        {
            "id": "46acd63c-be57-4993-ae8d-0e4067ad1d57",
            "text": "Your {{app_name}} verification code is: {{code}}. This code will expire in {{default_verification_timeout_secs}} minutes."
        },
        {
            "id": "723ead5e-ada6-4c29-a962-349170866187",
            "text": "{{code}} is your verification code for {{app_name}}. This code will expire in {{default_verification_timeout_secs}} minutes."
        },
        {
            "id": "88d0781f-f4c7-4b78-8d0a-1f3e4de78b5e",
            "text": "Your {{app_name}} verification code is: {{code}}. This code will expire in {{default_verification_timeout_secs}} minutes. Do not share this code with anyone; our employees will never ask for the code."
        }
    ]
}

Note: If not selected then the default template is "Your verification code is {code}."

Create a verify profile​

curl --location --request POST 'https://api.telnyx.com/v2/verify_profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "name": "foobar-en-v1",
    "language": "en-US",
    "sms": {
        "messaging_template_id": "0abb5b4f-459f-445a-bfcd-488998b7572d",
        "whitelisted_destinations": ["US", "CA"],
        "default_timeout_secs": 300,
        "code_length": 5
    },
    "call": {
        "default_timeout_secs": 600
    }
}'

Note: After pasting the above content, Kindly check and remove any new line added

Example Response​

{
    "data": {
        "id": "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
        "name": "foobar-en-v1",
        "created_at": "2024-03-27T11:45:41.292913",
        "updated_at": "2024-03-27T11:45:41.292913",
        "record_type": "verify_profile",
        "sms": {
            "messaging_template_id": "0abb5b4f-459f-445a-bfcd-488998b7572d",
            "whitelisted_destinations": ["US", "CA"],
            "default_timeout_secs": 300,
            "code_length": 5
        },
        "call": {
            "default_timeout_secs": 600
        },
        "flashcall": null,
        "language": "en-US"
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

Notes:

  • Don’t forget to update YOUR_API_KEY in each of these commands.

Take note of the profile's id that's returned to you, you'll need it to send 2FA verifications. At any time, you can access all of your created Verify Profiles by API as well.

You are now ready to send 2-factor authentication messages!

Step 2: Trigger a Verification Request​

To send a verification attempt, you need the Verify Profile ID, the phone number that will receive the message, and the verification type. Replace the fields below with your information to try one out for size:

Initiate an SMS verification request​

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"phone_number":"+13035551234","verify_profile_id":"4900017a-e7c8-e79e-0a7c-0d98f49b09cc"}' \
  https://api.telnyx.com/v2/verifications/sms

Note: After pasting the above content, Kindly check and remove any new line added

Example Response​

{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "phone_number": "+13035551234",
    "record_type": "verification",
    "status": "pending",
    "timeout_secs": 300,
    "verify_profile_id": "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
    "type": "sms",
    "updated_at": "2020-09-14T17:03:32.965812"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Our servers will send the message to the phone number you gave us, and now your user has the added security of 2FA.

Simialrly, you can use other modes of delivery to send verification codes. You can find the full specification here.

Step 3: Verify a 2FA code​

The user will send you the code they received on their device. Telnyx has saved that code, and all you have to do is check with us to see that they match, like this:

Verify a 2FA code​

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"code":"17686", "verify_profile_id": "UUID"}' \
  https://api.telnyx.com/v2/verifications/by_phone_number/+13035551234/actions/verify

Note: After pasting the above content, Kindly check and remove any new line added

Example response​

{
  "data": {
    "phone_number": "+13035551234",
    "response_code": "accepted"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

Make sure you put the correct phone number in that URL in E.164 format, and the code that was received in the data payload. Once you've done that, you should receive a response with a response_code of "accepted", to let you know that the user did indeed have the correct code. You've added extra security and peace of mind ensuring that your customer is who they say they are. And just like that, you're done!

If you need to check up on a 2FA verification, you can do that using the id.

You can view the docs for more details on endpoints related to Telnyx's Verify product.

On this page​