Open SidemenuDocs
Docs
Close Sidemenu
Choose:
cURL
cURL

Quickstart - Verify quickstart---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 curlTelnyx Developers command.


Portal Setup

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

Development Environment Setup

Check out the Development Environment Setup 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 WLSTelnyx Developers.

Methods of verification

There are currently five verification methods available.

  • sms, 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
  • whatsapp, the code is sent via WhatsApp
  • psd2, a PSD2Telnyx Developers compliant sms variation for payment services.

Step 1: Create a Verify Profilestep-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, speech to text calling, and WhatsApp - with webhooks configured.

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",
    "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}"
    },
    "whatsapp": {
        "app_name": "FooBar",
        "default_verification_timeout_secs": 60
    }
}'

Example Response

{
    "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
        },
        "whatsapp": {
            "enabled": true,
            "default_timeout_secs": 600,
            "app_name": "FooBar"
        },
        "flashcall": null,
        "language": "en-US",
        "webhook_url": "https://example.net/hook_1",
        "webhook_failover_url": "https://backup.example.net/hook_2"
    }
}

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 Requeststep-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

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"
  }
}

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.Telnyx Developers

Step 3: Verify a 2FA Codestep-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"}' \
  https://api.telnyx.com/v2/verifications/by_phone_number/+13035551234/actions/verify

Example Response

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

Make sure you put the correct phone number in that URL, 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 got back in Step 2, or by the phone number you sent it to.

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

Was this page helpful?