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 five verification methods available.

  • sms & vsms , the verification code is sent in a custom or default templated message
  • call , the code is spoken aloud when the user answers the call
  • flashcall , the phone number of the caller is used as the verification code
  • psd2 , a PSD2 compliant sms variation for payment services.

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 and speech to text calling- with webhooks configured.

Create a Verify Profile

Copy
Copied
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",
    "webhook_url": "https://example.net/hook_1",
    "webhook_failover_url": "https://backup.example.net/hook_2",
    "call": {
        "default_verification_timeout_secs": 90
    },
    "sms": {
        "messaging_template": "My custom template. Your code is: {code}"
    }
}'

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

Example Response

Copy
Copied
{
    "data": {
        "id": "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
        "name": "foobar-en-v1",
        "created_at": "2021-07-27T11:45:41.292913",
        "updated_at": "2021-07-27T11:45:41.292913",
        "record_type": "verify_profile",
        "enabled": true,
        "messaging_enabled": true,
        "messaging_template": "My custom template. Your code is: {code}",
        "default_timeout_secs": 300,
        "rcs_enabled": false,
        "vsms_enabled": false,
        "sms": {
            "enabled": true,
            "messaging_enabled": true,
            "messaging_template": "My custom template. Your code is: {code}",
            "default_timeout_secs": 300,
            "rcs_enabled": false,
            "vsms_enabled": false
        },
        "psd2": null,
        "call": {
            "enabled": true,
            "messaging_template": "Your verification code is {code}.",
            "default_timeout_secs": 600,
            "default_call_timeout_sec": 30
        },
        "flashcall": null,
        "language": "en-US",
        "webhook_url": "https://example.net/hook_1",
        "webhook_failover_url": "https://backup.example.net/hook_2"
    }
}

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.
  • Google RCS is not yet available, but is in our product pipeline very soon.

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

Copy
Copied
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

Copy
Copied
{
  "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

Copy
Copied
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"code":"17686", "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

Copy
Copied
{
  "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.