Open SidemenuDocs
Docs
Close Sidemenu
Choose:
cURLPythonRubyNode
cURLPythonRubyNode

Quickstartquickstart

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.


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. You can use a command like this to do it:

Create a Verify Profile

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"name":"Test Profile","default_timeout_secs":300,"messaging_enabled":true}' \
  https://api.telnyx.com/v2/verify_profiles

Example Response

{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "default_timeout_secs": 300,
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "messaging_enabled": true,
    "messaging_template": "Hello, this is the Acme Inc verification code you requested: {code}.",
    "name": "Test Profile",
    "rcs_enabled": false,
    "record_type": "verify_profile",
    "updated_at": "2020-09-14T17:03:32.965812"
  }
}

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 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 (only sms is supported at the moment). Replace the fields below with your information to try one out for size:

Initiate 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":"12ade33a-21c0-473b-b055-b3c836e1c292","type":"sms"}' \
  https://api.telnyx.com/v2/verifications

Example Response

{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "phone_number": "+13035551234",
    "record_type": "verification",
    "status": "accepted",
    "timeout_secs": 300,
    "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "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.

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?