Telnyx Numbers: Identity — Full Documentation

Complete page content for Identity (Numbers section) of the Telnyx developer docs (https://developers.telnyx.com). This file: https://developers.telnyx.com/development/llms/numbers-identity-llms-full-txt.md · Root index: https://developers.telnyx.com/llms.txt

Number Lookup

Number lookup using Telnyx APIs

Source: https://developers.telnyx.com/docs/identity/number-lookup/quickstart.md

Lookup: Carrier and caller name

cURL

Number Lookup is a service offered by the Telnyx SDK that allows the user to look up a phone number and retrieve information regarding that phone number such as:

Carrier name
Type of phone (landline, mobile, etc.)
Name and business associated with the number

Basic number lookup example

Running the following code will perform a number lookup on the given number parameter. Don’t forget to update YOUR_API_KEY here.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/number_lookup/+18665552368"

After pasting the above content, Kindly check and remove any new line added The response will look something like this:

{
  "data": {
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "carrier": {
      "error_code": null,
      "mobile_country_code": "US",
      "mobile_network_code": 866,
      "name": "Telnyx/4",
      "type": "voip"
    },
    "country_code": "US",
    "fraud": null,
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "portability": {
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "line_type": "voip",
      "lrn": "2245701999",
      "ocn": "073H",
      "ported_date": "2017-10-20",
      "ported_status": "Y",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "state": "Illinois"
    },
    "record_type": "number_lookup"
  }
}

After pasting the above content, Kindly check and remove any new line added This example shows results for a Telnyx user-owned number. It displays the formatted version of the number in the national-format value. The location of the number can be seen under portability -> city and state. Other useful information such as carrier and caller_name can be retrieved if available.

Retrieving caller name and carrier

Users may also specify the type of the request in order to receive information about the carrier and caller-name. Note that the request will always return the same object, however if the caller-name and carrier options are not sent, the return values will be null. An example of adding both these parameters to the request is shown below:

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/number_lookup/+18665552368?carrier&caller-name"

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

Python

Number Lookup is a serviceis a service offered by the Telnyx SDK that allows the user to look up a phone number and retrieve information regarding that phone number such as:

Carrier name
Type of phone (landline, mobile, etc.)
Name and business associated with the number

Basic number lookup example

Running the following code will perform a number lookup on the given number parameter using Python.

import telnyx
telnyx.api_key = "YOUR_API_KEY"
telnyx.NumberLookup.retrieve(“+13129457420”)

After pasting the above content, Kindly check and remove any new line added The response will look something like this:

{
  "data": {
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "carrier": {
      "error_code": null,
      "mobile_country_code": "US",
      "mobile_network_code": 866,
      "name": "Telnyx/4",
      "type": "voip"
    },
    "country_code": "US",
    "fraud": null,
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "portability": {
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "line_type": "voip",
      "lrn": "2245701999",
      "ocn": "073H",
      "ported_date": "2017-10-20",
      "ported_status": "Y",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "state": "Illinois"
    },
    "record_type": "number_lookup"
  }
}

Retrieving caller name and carrier

Node

Number Lookup is a serviceoffered by the Telnyx SDK that allows the user to look up a phone number and retrieve information regarding that phone number such as:

Carrier name
Type of phone (landline, mobile, etc.)
Name and business associated with the number

Basic number lookup example

Running the following code will perform a number lookup on the given number parameter.

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

// In Node 10
const { data: numberInfo } = await telnyx.numberLookup.retrieve(
  '+18665552368'
);

// In other environments
telnyx.numberLookup.retrieve(
  '+18665552368'
).then(function(response){
  const numberInfo = response.data; // asynchronously handled
});

After pasting the above content, Kindly check and remove any new line added The response will look something like this:

{
  "data": {
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "carrier": {
      "error_code": null,
      "mobile_country_code": "US",
      "mobile_network_code": 866,
      "name": "Telnyx/4",
      "type": "voip"
    },
    "country_code": "US",
    "fraud": null,
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "portability": {
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "line_type": "voip",
      "lrn": "2245701999",
      "ocn": "073H",
      "ported_date": "2017-10-20",
      "ported_status": "Y",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "state": "Illinois"
    },
    "record_type": "number_lookup"
  }
}

Retrieving caller name and carrier

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

// In Node 10
const { data: numberInfo } = await telnyx.numberLookup.retrieve(
  '+18665552368',
  {
    type: ["caller-name", "carrier"]
  }
);

// In other environments
telnyx.numberLookup.retrieve(
  '+18665552368',
  {
    type: ["caller-name", "carrier"]
  }
).then(function(response){
  const numberInfo = response.data; // asynchronously handled
});

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

Ruby

Number Lookup is a service is a service offered by the Telnyx SDK that allows the user to look up a phone number and retrieve information regarding that phone number such as:

Carrier name
Type of phone (landline, mobile, etc.)
Name and business associated with the number

Basic number lookup example

Running the following code will perform a number lookup on the given number parameter.

require "telnyx"
Telnyx.api_key = "YOUR_API_KEY"

Telnyx::NumberLookup.retrieve('+12624755500')

After pasting the above content, Kindly check and remove any new line added The response will look something like this:

{
  "data": {
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "carrier": {
      "error_code": null,
      "mobile_country_code": "US",
      "mobile_network_code": 866,
      "name": "Telnyx/4",
      "type": "voip"
    },
    "country_code": "US",
    "fraud": null,
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "portability": {
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "line_type": "voip",
      "lrn": "2245701999",
      "ocn": "073H",
      "ported_date": "2017-10-20",
      "ported_status": "Y",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "state": "Illinois"
    },
    "record_type": "number_lookup"
  }
}

Retrieving caller name and carrier

Verify

Telnyx verify quickstart

Source: https://developers.telnyx.com/docs/identity/verify/quickstart.md

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. Examples are provided in curl, Node.js, Python, Ruby, Go, Java, .NET, and PHP.

Prerequisites

Sign up at telnyx.com if you don’t have an account yet. Follow the API Keys guide to generate an API key. Set it as an environment variable:

macOS/Linux

export TELNYX_API_KEY="YOUR_API_KEY"

Windows

$env:TELNYX_API_KEY = "YOUR_API_KEY"

If you prefer using an SDK over curl, install one for your language:

Node.js

npm install telnyx

Python

pip install telnyx

Ruby

gem install telnyx

go get github.com/team-telnyx/telnyx-go

PHP

composer require telnyx/telnyx-php

For Java and .NET, the examples use the standard HTTP client libraries included with the platform.

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 verification code is embedded in the caller ID of a brief “flash” call (the call rings once and hangs up). The user’s app extracts the code automatically.

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

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

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const templates = await client.verifyProfiles.retrieveTemplates();

for (const template of templates.data) {
  console.log(`${template.id}: ${template.text}`);
}

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

templates = client.verify_profiles.retrieve_templates()

for template in templates.data:
    print(f"{template.id}: {template.text}")

Ruby

require "telnyx"
require "json"
require "net/http"
require "uri"

uri = URI("https://api.telnyx.com/v2/verify_profiles/templates")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

data["data"].each do |template|
  puts "#{template['id']}: #{template['text']}"
end

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(option.WithAPIKey(os.Getenv("TELNYX_API_KEY")))

  templates, err := client.VerifyProfiles.RetrieveTemplates(context.TODO())
  if err != nil {
    panic(err)
  }
  for _, t := range templates.Data {
    fmt.Printf("%s: %s\n", t.ID, t.Text)
  }
}

Java

package com.telnyx.example;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public final class ListTemplates {
    public static void main(String[] args) throws Exception {
        HttpClient httpClient = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.telnyx.com/v2/verify_profiles/templates"))
            .header("Authorization", "Bearer " + System.getenv("TELNYX_API_KEY"))
            .GET()
            .build();

        HttpResponse<String> response = httpClient.send(
            request, HttpResponse.BodyHandlers.ofString()
        );
        System.out.println(response.body());
    }
}

.NET

using System.Net.Http.Headers;

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var response = await httpClient.GetStringAsync(
    "https://api.telnyx.com/v2/verify_profiles/templates"
);
Console.WriteLine(response);

PHP

<?php
require_once 'vendor/autoload.php';

$apiKey = getenv('TELNYX_API_KEY');

$ch = curl_init('https://api.telnyx.com/v2/verify_profiles/templates');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
    ],
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['data'] as $template) {
    echo "{$template['id']}: {$template['text']}\n";
}

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

If not selected then the default template is “Your verification code is {code}.” Want to use your own branded verification messages? You can now create custom templates that match your brand voice and compliance requirements.

Create a verify profile

curl

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

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const profile = await client.verifyProfiles.create({
  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,
  },
});

console.log('Profile ID:', profile.data.id);
console.log('Profile name:', profile.data.name);

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

profile = client.verify_profiles.create(
    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,
    },
)

print(f"Profile ID: {profile.data.id}")
print(f"Profile name: {profile.data.name}")

Ruby

require "telnyx"
require "json"
require "net/http"
require "uri"

uri = URI("https://api.telnyx.com/v2/verify_profiles")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
req.body = {
  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
  }
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

puts "Profile ID: #{data['data']['id']}"
puts "Profile name: #{data['data']['name']}"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(option.WithAPIKey(os.Getenv("TELNYX_API_KEY")))

  profile, err := client.VerifyProfiles.Create(context.TODO(), telnyx.VerifyProfileCreateParams{
    Name:     "foobar-en-v1",
    Language: telnyx.String("en-US"),
    SMS: &telnyx.VerifyProfileSMSParams{
      MessagingTemplateID:    telnyx.String("0abb5b4f-459f-445a-bfcd-488998b7572d"),
      WhitelistedDestinations: []string{"US", "CA"},
      DefaultTimeoutSecs:     telnyx.Int64(300),
      CodeLength:             telnyx.Int64(5),
    },
    Call: &telnyx.VerifyProfileCallParams{
      DefaultTimeoutSecs: telnyx.Int64(600),
    },
  })
  if err != nil {
    panic(err)
  }
  fmt.Printf("Profile ID: %s\n", profile.Data.ID)
  fmt.Printf("Profile name: %s\n", profile.Data.Name)
}

Java

package com.telnyx.example;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public final class CreateVerifyProfile {
    public static void main(String[] args) throws Exception {
        String body = """
            {
                "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
                }
            }
            """;

        HttpClient httpClient = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.telnyx.com/v2/verify_profiles"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + System.getenv("TELNYX_API_KEY"))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = httpClient.send(
            request, HttpResponse.BodyHandlers.ofString()
        );
        System.out.println(response.body());
    }
}

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var payload = new
{
    name = "foobar-en-v1",
    language = "en-US",
    sms = new
    {
        messaging_template_id = "0abb5b4f-459f-445a-bfcd-488998b7572d",
        whitelisted_destinations = new[] { "US", "CA" },
        default_timeout_secs = 300,
        code_length = 5
    },
    call = new { default_timeout_secs = 600 }
};

var content = new StringContent(
    JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json"
);
var response = await httpClient.PostAsync(
    "https://api.telnyx.com/v2/verify_profiles", content
);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

PHP

<?php
require_once 'vendor/autoload.php';

$apiKey = getenv('TELNYX_API_KEY');

$payload = json_encode([
    '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,
    ],
]);

$ch = curl_init('https://api.telnyx.com/v2/verify_profiles');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
        'Content-Type: application/json',
    ],
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Profile ID: " . $data['data']['id'] . "\n";
echo "Profile name: " . $data['data']['name'] . "\n";

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
        },
        "language": "en-US"
    }
}

Don’t forget to set your TELNYX_API_KEY environment variable or replace YOUR_API_KEY in the curl examples. 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!

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. Choose the method that best fits your use case: SMS verification sends a code via text message. This is the most common method with the widest global coverage.

curl

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

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const verification = await client.verifications.triggerSMS({
  phone_number: '+13035551234',
  verify_profile_id: '4900017a-e7c8-e79e-0a7c-0d98f49b09cc'
});

console.log('Verification ID:', verification.data.id);
console.log('Status:', verification.data.status); // "pending"

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

verification = client.verifications.trigger_sms(
    phone_number="+13035551234",
    verify_profile_id="4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

print(f"Verification ID: {verification.data.id}")
print(f"Status: {verification.data.status}")  # "pending"

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

verification = client.verifications.sms(
  phone_number: "+13035551234",
  verify_profile_id: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

puts "Verification ID: #{verification.id}"
puts "Status: #{verification.status}" # "pending"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(option.WithAPIKey(os.Getenv("TELNYX_API_KEY")))

  verification, err := client.Verifications.SMS(context.TODO(), telnyx.VerificationSMSParams{
    PhoneNumber:     "+13035551234",
    VerifyProfileID: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
  })
  if err != nil {
    panic(err)
  }
  fmt.Printf("Verification ID: %s\n", verification.Data.ID)
  fmt.Printf("Status: %s\n", verification.Data.Status) // "pending"
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.verify.VerificationParams;
import com.telnyx.sdk.models.verify.VerificationResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        VerificationParams params = VerificationParams.builder()
            .phoneNumber("+13035551234")
            .verifyProfileId("4900017a-e7c8-e79e-0a7c-0d98f49b09cc")
            .build();

        VerificationResponse response = client.verifications().sms(params);
        System.out.println("Verification ID: " + response.getId());
        System.out.println("Status: " + response.getStatus()); // "pending"
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new VerificationService();
var response = await service.SendSmsAsync(new VerificationSmsOptions
{
    PhoneNumber = "+13035551234",
    VerifyProfileId = "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
});

Console.WriteLine($"Verification ID: {response.Data.Id}");
Console.WriteLine($"Status: {response.Data.Status}"); // "pending"

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$verification = \Telnyx\Verification::create([
    'phone_number' => '+13035551234',
    'verify_profile_id' => '4900017a-e7c8-e79e-0a7c-0d98f49b09cc',
    'type' => 'sms'
]);

echo "Verification ID: " . $verification->id . "\n";
echo "Status: " . $verification->status . "\n"; // "pending"

User experience: The user receives a text message with a numeric code (e.g., “Your verification code is: 17686”). They enter this code in your application. Call verification speaks the code aloud when the user answers. Useful when the user cannot receive SMS (landlines, VoIP) or in regions with unreliable SMS delivery. Profile configuration for call: When creating your verify profile, include the call configuration:

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": "my-app-call-verify",
    "language": "en-US",
    "call": {
        "default_timeout_secs": 600
    }
}'

Initiate a call verification:

curl

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/call

Node

const verification = await client.verifications.triggerCall({
  phone_number: '+13035551234',
  verify_profile_id: '4900017a-e7c8-e79e-0a7c-0d98f49b09cc'
});

console.log('Verification ID:', verification.data.id);
console.log('Type:', verification.data.type); // "call"

Python

verification = client.verifications.trigger_call(
    phone_number="+13035551234",
    verify_profile_id="4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

print(f"Verification ID: {verification.data.id}")
print(f"Type: {verification.data.type}")  # "call"

Ruby

verification = client.verifications.call(
  phone_number: "+13035551234",
  verify_profile_id: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

puts "Verification ID: #{verification.id}"
puts "Type: #{verification.type}" # "call"

verification, err := client.Verifications.Call(context.TODO(), telnyx.VerificationCallParams{
  PhoneNumber:     "+13035551234",
  VerifyProfileID: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
})
if err != nil {
  panic(err)
}
fmt.Printf("Verification ID: %s\n", verification.Data.ID)

Java

VerificationResponse response = client.verifications().call(
    VerificationParams.builder()
        .phoneNumber("+13035551234")
        .verifyProfileId("4900017a-e7c8-e79e-0a7c-0d98f49b09cc")
        .build()
);
System.out.println("Verification ID: " + response.getId());

.NET

var response = await service.SendCallAsync(new VerificationCallOptions
{
    PhoneNumber = "+13035551234",
    VerifyProfileId = "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
});

Console.WriteLine($"Verification ID: {response.Data.Id}");

PHP

$verification = \Telnyx\Verification::create([
    'phone_number' => '+13035551234',
    'verify_profile_id' => '4900017a-e7c8-e79e-0a7c-0d98f49b09cc',
    'type' => 'call'
]);

echo "Verification ID: " . $verification->id . "\n";

User experience: The user receives a phone call. An automated voice reads the verification code aloud (e.g., “Your verification code is 1-7-6-8-6”). The code is repeated twice. The user then enters the code in your application. DTMF confirmation: You can optionally enable DTMF confirmation, where the user enters the code on their phone keypad during the call instead of typing it in your app. See the DTMF Confirmation guide for details.

Example response (all methods)

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

Choosing the right verification method

Feature	SMS	Call	Flashcall
Delivery speed	1–5 seconds	10–20 seconds (ring + answer)	2–5 seconds
User interaction	Read code, type it in	Listen to code, type it in	Automatic (app reads caller ID)
Works on web	✅ Yes	✅ Yes	❌ No (mobile only)
Works on landlines	❌ No	✅ Yes	❌ No
Cost	Per-message rate	Per-minute rate	Per-call rate (very short)
Global coverage	Widest	Wide	Limited
Accessibility	Good	Best (audio)	App-dependent
Best for	General purpose	Landlines, accessibility	Mobile apps with auto-read

Fallback strategy: Configure multiple methods in your verify profile. Start with SMS (fastest and widest coverage), fall back to call if SMS fails. For mobile apps, consider flashcall as a zero-friction primary method with SMS as fallback.

Verify a 2FA code

The user provides the code they received (via SMS or call). Submit it to Telnyx to verify it matches:

curl

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

Node

const result = await client.verifications.byPhoneNumber.actions.verify(
  '+13035551234',
  {
    code: '17686',
    verify_profile_id: '4900017a-e7c8-e79e-0a7c-0d98f49b09cc',
  }
);

if (result.data.response_code === 'accepted') {
  console.log('Verification successful!');
} else {
  console.log('Verification failed:', result.data.response_code);
}

Python

result = client.verifications.by_phone_number.actions.verify(
    "+13035551234",
    code="17686",
    verify_profile_id="4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

if result.data.response_code == "accepted":
    print("Verification successful!")
else:
    print(f"Verification failed: {result.data.response_code}")

Ruby

result = client.verifications.verify(
  "+13035551234",
  code: "17686",
  verify_profile_id: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

if result.response_code == "accepted"
  puts "Verification successful!"
else
  puts "Verification failed: #{result.response_code}"
end

result, err := client.Verifications.Verify(context.TODO(), "+13035551234", telnyx.VerificationVerifyParams{
  Code:            "17686",
  VerifyProfileID: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
})
if err != nil {
  panic(err)
}
if result.Data.ResponseCode == "accepted" {
  fmt.Println("Verification successful!")
} else {
  fmt.Printf("Verification failed: %s\n", result.Data.ResponseCode)
}

Java

VerifyResponse result = client.verifications().verify(
    "+13035551234",
    VerifyParams.builder()
        .code("17686")
        .verifyProfileId("4900017a-e7c8-e79e-0a7c-0d98f49b09cc")
        .build()
);

if ("accepted".equals(result.getResponseCode())) {
    System.out.println("Verification successful!");
} else {
    System.out.println("Verification failed: " + result.getResponseCode());
}

.NET

var result = await service.VerifyAsync("+13035551234", new VerifyCodeOptions
{
    Code = "17686",
    VerifyProfileId = "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
});

if (result.Data.ResponseCode == "accepted")
    Console.WriteLine("Verification successful!");
else
    Console.WriteLine($"Verification failed: {result.Data.ResponseCode}");

PHP

$result = \Telnyx\Verification::verify('+13035551234', [
    'code' => '17686',
    'verify_profile_id' => '4900017a-e7c8-e79e-0a7c-0d98f49b09cc'
]);

if ($result->response_code === 'accepted') {
    echo "Verification successful!\n";
} else {
    echo "Verification failed: " . $result->response_code . "\n";
}

Example response

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

A response_code of "accepted" confirms the code matches. Other possible values:

Response Code	Meaning
`accepted`	Code is correct - verification successful
`rejected`	Code is incorrect
`expired`	Verification timed out (exceeded `timeout_secs`)
`max_attempts_exceeded`	Too many incorrect attempts

Telnyx Verify supports webhooks to receive instant notifications when users complete verification, eliminating the need for polling. This enables event-driven workflows for faster user experiences. Learn more: Receiving Webhooks for Telnyx Verify

Next steps

Now that you’ve completed a basic verification flow, explore these guides to build a production-ready implementation: Create branded verification messages that match your app’s voice and compliance requirements. Protect against SMS pumping, brute force attacks, and other verification fraud. Receive real-time notifications when verifications complete or expire. Complete login, registration, and payment verification flow implementations.

DTMF confirmation

Source: https://developers.telnyx.com/docs/identity/verify/dtmf-confirm.md

DTMF confirmation calls a phone number, plays a TTS prompt, and collects a single keypress (1) to confirm ownership. No verification code is generated — the keypress is the confirmation. The POST /verifications/{id}/actions/verify endpoint is not used. Verification completes on the call itself. DTMF confirmation is unique to Telnyx — Twilio and Vonage Verify APIs only support code-based voice verification (read a code, then type it). Single-keypress confirmation reduces user friction and works on landlines.

Flow

Outcome	Trigger	Status
Confirmed	Digit `1` pressed	`accepted`
Rejected	Wrong digit	`invalid`
Timed out	No keypress (10s)	`expired`
Failed	Call not answered	`error`

Up to 3 attempts per call. After 3 wrong digits, the call ends with status invalid.

Use cases

Confirm ownership before allowing a number as outbound Caller ID. Verify numbers that cannot receive SMS. Single keypress instead of reading and typing a code. Confirm phone ownership without code entry.

Create a verify profile

Create a profile with dtmf_confirm settings. This can be combined with other verification types (SMS, call) on the same profile.

curl

curl -X POST https://api.telnyx.com/v2/verify_profiles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -d '{
    "name": "caller-id-verification",
    "language": "en-US",
    "dtmf_confirm": {
      "default_timeout_secs": 300
    }
  }'

Python

import os
import telnyx

telnyx.api_key = os.environ["TELNYX_API_KEY"]

profile = telnyx.VerifyProfile.create(
    name="caller-id-verification",
    language="en-US",
    dtmf_confirm={"default_timeout_secs": 300},
)
profile_id = profile.id

Node

const telnyx = require('telnyx')(process.env.TELNYX_API_KEY);

const profile = await telnyx.verifyProfiles.create({
  name: 'caller-id-verification',
  language: 'en-US',
  dtmf_confirm: { default_timeout_secs: 300 },
});
const profileId = profile.data.id;

Ruby

require 'telnyx'

Telnyx.api_key = ENV['TELNYX_API_KEY']

profile = Telnyx::VerifyProfile.create(
  name: 'caller-id-verification',
  language: 'en-US',
  dtmf_confirm: { default_timeout_secs: 300 }
)
profile_id = profile.id

package main

import (
    "os"
    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient(os.Getenv("TELNYX_API_KEY"))

    profile, _ := client.VerifyProfiles.Create(&telnyx.VerifyProfileParams{
        Name:     "caller-id-verification",
        Language: "en-US",
        DTMFConfirm: &telnyx.DTMFConfirmSettings{
            DefaultTimeoutSecs: 300,
        },
    })
    profileID := profile.ID
}

Java

import com.telnyx.sdk.*;
import com.telnyx.sdk.api.VerifyApi;
import com.telnyx.sdk.model.*;

ApiClient client = Configuration.getDefaultApiClient();
client.setBearerToken(System.getenv("TELNYX_API_KEY"));

VerifyApi api = new VerifyApi(client);
CreateVerifyProfileRequest request = new CreateVerifyProfileRequest()
    .name("caller-id-verification")
    .language("en-US")
    .dtmfConfirm(new DTMFConfirmSettings().defaultTimeoutSecs(300));

VerifyProfileResponse profile = api.createVerifyProfile(request);
String profileId = profile.getData().getId();

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new VerifyProfileService();
var profile = service.Create(new VerifyProfileCreateOptions
{
    Name = "caller-id-verification",
    Language = "en-US",
    DtmfConfirm = new DtmfConfirmSettings
    {
        DefaultTimeoutSecs = 300
    }
});
var profileId = profile.Id;

PHP

require 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$profile = \Telnyx\VerifyProfile::create([
    'name' => 'caller-id-verification',
    'language' => 'en-US',
    'dtmf_confirm' => ['default_timeout_secs' => 300],
]);
$profileId = $profile->id;

The returned id is required for verification requests.

Trigger verification

curl

curl -X POST https://api.telnyx.com/v2/verifications/dtmf_confirm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -d '{
    "phone_number": "+13035551234",
    "verify_profile_id": "YOUR_PROFILE_ID"
  }'

Python

verification = telnyx.Verification.create(
    phone_number="+13035551234",
    verify_profile_id=profile_id,
    type="dtmf_confirm",
)

Node

const verification = await telnyx.verifications.create({
  phone_number: '+13035551234',
  verify_profile_id: profileId,
  type: 'dtmf_confirm',
});

Ruby

verification = Telnyx::Verification.create(
  phone_number: '+13035551234',
  verify_profile_id: profile_id,
  type: 'dtmf_confirm'
)

verification, _ := client.Verifications.Create(&telnyx.VerificationParams{
    PhoneNumber:     "+13035551234",
    VerifyProfileID: profileID,
    Type:            "dtmf_confirm",
})

Java

CreateVerificationRequest verReq = new CreateVerificationRequest()
    .phoneNumber("+13035551234")
    .verifyProfileId(profileId)
    .type(CreateVerificationRequest.TypeEnum.DTMF_CONFIRM);

VerificationResponse ver = api.createVerification(verReq);

.NET

var verService = new VerificationService();
var verification = verService.Create(new VerificationCreateOptions
{
    PhoneNumber = "+13035551234",
    VerifyProfileId = profileId,
    Type = "dtmf_confirm"
});

PHP

$verification = \Telnyx\Verification::create([
    'phone_number' => '+13035551234',
    'verify_profile_id' => $profileId,
    'type' => 'dtmf_confirm',
]);

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "phone_number": "+13035551234",
    "record_type": "verification",
    "status": "pending",
    "type": "dtmf_confirm",
    "timeout_secs": 300,
    "verify_profile_id": "YOUR_PROFILE_ID",
    "created_at": "2026-02-20T15:30:00.000000",
    "updated_at": "2026-02-20T15:30:00.000000"
  }
}

Default TTS prompt:

“This is a verification call to confirm that this phone number is going to be used as a Caller ID for outbound calls. If you did not request this verification, or if someone is asking you to accept this call, please ignore this message. If you did request this verification, please press 1.”

The TTS language is determined by the language field on the Verify Profile (default: en-US).

Handle the result

Verification completes on the call — no verify endpoint call needed. Receive the outcome via webhooks.

Accepted (digit `1` pressed)

{
  "data": {
    "event_type": "verification.complete",
    "payload": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "phone_number": "+13035551234",
      "status": "accepted",
      "type": "dtmf_confirm",
      "verify_profile_id": "YOUR_PROFILE_ID"
    }
  }
}

Failed (wrong digit, timeout, or call failure)

{
  "data": {
    "event_type": "verification.complete",
    "payload": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "phone_number": "+13035551234",
      "status": "invalid",
      "type": "dtmf_confirm",
      "verify_profile_id": "YOUR_PROFILE_ID"
    }
  }
}

Polling alternative

curl https://api.telnyx.com/v2/verifications/{verification_id} \
  -H "Authorization: Bearer $TELNYX_API_KEY"

Complete example

Full flow: create profile, trigger verification, handle webhook.

import os
import telnyx
from flask import Flask, request, jsonify

telnyx.api_key = os.environ["TELNYX_API_KEY"]
app = Flask(__name__)

# Create profile (once)
profile = telnyx.VerifyProfile.create(
    name="dtmf-verification",
    language="en-US",
    dtmf_confirm={"default_timeout_secs": 300},
)

# Trigger verification
verification = telnyx.Verification.create(
    phone_number="+13035551234",
    verify_profile_id=profile.id,
    type="dtmf_confirm",
)
print(f"Verification {verification.id} — {verification.status}")

@app.route("/webhooks/verify", methods=["POST"])
def handle_webhook():
    payload = request.json["data"]["payload"]

    if payload["status"] == "accepted":
        print(f"✅ {payload['phone_number']} verified")
    else:
        print(f"❌ {payload['phone_number']} failed: {payload['status']}")

    return jsonify({"status": "ok"}), 200

app.run(port=5000)

const express = require('express');
const telnyx = require('telnyx')(process.env.TELNYX_API_KEY);

const app = express();
app.use(express.json());

(async () => {
  // Create profile (once)
  const profile = await telnyx.verifyProfiles.create({
    name: 'dtmf-verification',
    language: 'en-US',
    dtmf_confirm: { default_timeout_secs: 300 },
  });

  // Trigger verification
  const verification = await telnyx.verifications.create({
    phone_number: '+13035551234',
    verify_profile_id: profile.data.id,
    type: 'dtmf_confirm',
  });
  console.log(`Verification ${verification.data.id} — ${verification.data.status}`);

  // Handle webhook
  app.post('/webhooks/verify', (req, res) => {
    const { phone_number, status } = req.body.data.payload;

    if (status === 'accepted') {
      console.log(`✅ ${phone_number} verified`);
    } else {
      console.log(`❌ ${phone_number} failed: ${status}`);
    }

    res.json({ status: 'ok' });
  });

  app.listen(5000, () => console.log('Webhook server on :5000'));
})();

require 'telnyx'
require 'sinatra'
require 'json'

Telnyx.api_key = ENV['TELNYX_API_KEY']

# Create profile (once)
profile = Telnyx::VerifyProfile.create(
  name: 'dtmf-verification',
  language: 'en-US',
  dtmf_confirm: { default_timeout_secs: 300 }
)

# Trigger verification
verification = Telnyx::Verification.create(
  phone_number: '+13035551234',
  verify_profile_id: profile.id,
  type: 'dtmf_confirm'
)
puts "Verification #{verification.id} — #{verification.status}"

# Handle webhook
post '/webhooks/verify' do
  payload = JSON.parse(request.body.read)['data']['payload']

  if payload['status'] == 'accepted'
    puts "✅ #{payload['phone_number']} verified"
  else
    puts "❌ #{payload['phone_number']} failed: #{payload['status']}"
  end

  { status: 'ok' }.to_json
end

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"

    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient(os.Getenv("TELNYX_API_KEY"))

    // Create profile (once)
    profile, _ := client.VerifyProfiles.Create(&telnyx.VerifyProfileParams{
        Name:     "dtmf-verification",
        Language: "en-US",
        DTMFConfirm: &telnyx.DTMFConfirmSettings{
            DefaultTimeoutSecs: 300,
        },
    })

    // Trigger verification
    ver, _ := client.Verifications.Create(&telnyx.VerificationParams{
        PhoneNumber:     "+13035551234",
        VerifyProfileID: profile.ID,
        Type:            "dtmf_confirm",
    })
    fmt.Printf("Verification %s — %s\n", ver.ID, ver.Status)

    // Handle webhook
    http.HandleFunc("/webhooks/verify", func(w http.ResponseWriter, r *http.Request) {
        var event struct {
            Data struct {
                Payload struct {
                    PhoneNumber string `json:"phone_number"`
                    Status      string `json:"status"`
                } `json:"payload"`
            } `json:"data"`
        }
        json.NewDecoder(r.Body).Decode(&event)

        p := event.Data.Payload
        if p.Status == "accepted" {
            fmt.Printf("✅ %s verified\n", p.PhoneNumber)
        } else {
            fmt.Printf("❌ %s failed: %s\n", p.PhoneNumber, p.Status)
        }
        w.Write([]byte(`{"status":"ok"}`))
    })

    http.ListenAndServe(":5000", nil)
}

Verification type comparison

Feature	SMS	Call	Flash Call	DTMF Confirm
User action	Type code	Listen + type code	None	Press 1
Code generated	Yes	Yes	Yes (caller ID)	No
Verify endpoint	Required	Required	Required	Not needed
Landline support	No	Yes	No	Yes
Fraud risk	SIM swap, interception	Low	Low	Low
Competitor support	Twilio, Vonage	Twilio, Vonage	Twilio	Telnyx only

Troubleshooting

Verification times out with status expired. Implement a retry with delay, or fall back to SMS. Up to 3 attempts per call. After 3 failures, status is invalid. Trigger a new verification to retry. Call was not answered and no webhook received. Verify the webhook URL is configured and reachable. Poll the status endpoint as fallback. The prompt is fixed to the standard verification message. Voice and language are determined by the Verify Profile’s language setting. Custom prompt text is not yet supported. Standard Verify API rate limits apply. Avoid triggering multiple concurrent verifications for the same phone number — the previous call must complete or time out first.

Next steps

Real-time verification status updates. Branded verification messages for SMS and call types. Full API specification. SMS and call verification guide.

Custom templates

Source: https://developers.telnyx.com/docs/identity/verify/custom-templates.md

Telnyx Verify now enables you to create and register your own verification message templates instantly. This feature allows you to build compliant, branded one-time password (OTP) messages that match your brand voice while maintaining security standards.

Overview

Custom templates give you complete control over your verification messaging. Instead of using pre-built templates, you can create personalized messages that:

Align with your brand guidelines and tone of voice.
Include industry-specific security warnings and disclaimers.
Maintain compliance with regulatory requirements.
Deploy instantly without manual approval processes.

When to use custom templates

Use custom templates when:

You need branded verification messages that match your company’s voice.
Your industry requires specific compliance language in OTP messages.
You want to include custom security warnings or instructions.
You need different templates for different user segments or regions.

Use pre-built templates when:

You’re getting started quickly and don’t need customization.
Standard verification messages meet your requirements.
You want to minimize setup time.

Template variables

All verification templates support the following variables that will be automatically replaced when sending verifications:

{{app_name}} - Your application name as configured in the verify profile.
{{code}} - The verification code sent to the user.

Creating custom templates

Use the Telnyx API to create custom verification message templates.

Create a custom template

curl -L 'https://api.telnyx.com/v2/verify_profiles/templates' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "text": "Your {{app_name}} verification code is {{code}}. Do not share this code."
  }'

Example response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "text": "Your {{app_name}} verification code is {{code}}. Do not share this code."
  }
}

Save the template id returned in the response. You’ll need this ID to reference the template when creating verify profiles. For complete API details, see the Create Message Template API reference.

Real-world template examples

Here are industry-specific template examples to inspire your custom messaging:

E-commerce and retail

Your {{app_name}} verification code is {{code}}. Complete your purchase securely.

Banking and finance

{{code}} is your {{app_name}} security code. Never share this with anyone, including our staff.

Healthcare and telemedicine

Your {{app_name}} appointment verification code: {{code}}. If you didn't request this, contact support immediately.

Welcome to {{app_name}}! Your verification code is {{code}}. Start connecting with friends now.

Delivery and logistics

Your {{app_name}} delivery confirmation code is {{code}}. Track your package now.

Travel and hospitality

{{code}} is your {{app_name}} booking verification code.

Using custom templates in verify profiles

Once you’ve created a custom template, reference its ID when creating or updating a verify profile.

Example: Create verify profile with custom template

curl -L 'https://api.telnyx.com/v2/verify_profiles' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "my-app-verification",
    "language": "en-US",
    "sms": {
      "messaging_template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "whitelisted_destinations": ["US", "CA"],
      "default_timeout_secs": 300,
      "code_length": 6
    }
  }'

The messaging_template_id field references your custom template. When you send verifications using this profile, your custom template will be used instead of the default.

Updating custom templates

You can update existing custom templates to refine messaging or fix errors.

Update a template

curl -L -X PATCH 'https://api.telnyx.com/v2/verify_profiles/templates/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "text": "Your {{app_name}} verification code is {{code}}. Contact support if you did not request this."
  }'

Example response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "text": "Your {{app_name}} verification code is {{code}}. Contact support if you did not request this."
  }
}

Updating a template affects all verify profiles that reference it. Test template changes carefully before updating production templates. For complete API details, see the Update Message Template API reference.

Best practices

Keep messages concise

SMS messages have character limits. Keep your templates under 160 characters when possible to avoid message splitting and additional costs.

Include security warnings

For sensitive use cases like banking or healthcare, include warnings about not sharing codes:

Never share this code with anyone, including our staff.
If you didn't request this, contact support immediately.

Test before production

Always test new templates in a development environment before using them in production verify profiles. Send test verifications to confirm:

Variables are replaced correctly.
Message formatting appears as expected.
Character count is within limits.
Links or special characters display properly.

Follow compliance guidelines

Ensure your templates comply with:

Industry regulations (HIPAA, PCI-DSS, GDPR, etc.).
Carrier requirements for SMS messaging.
Local laws regarding verification messages.
Your organization’s security policies.

Consider localization

If you serve multiple regions, create separate templates for different languages and cultures. Use the verify profile’s language parameter to organize templates by locale.

Next steps

Learn how to send verifications: Telnyx Verify quickstart
Configure webhooks for verification events: Receiving webhooks
View the complete Verify API reference: Verify API documentation

Webhooks

Source: https://developers.telnyx.com/docs/identity/verify/receiving-webhooks.md

You can choose to be notified about events on your send verifications by configuring webhooks on your verify profile.

Verify delivery status updates

The Telnyx Verify Service will attempt to notify you about the following delivery events for the send verification request:

verify.sent
verify.failed
verify.delivered

Delivery status Payload

Here is an example of a webhook event where a delivery receipt is returned to the sender after sending a verification:

{
  "data": {
    "event_type": "verify.delivered",
    "id": "3bb6321b-abd5-4d60-8cf8-1e6026bb1c41",
    "occurred_at": "2025-10-08T17:16:09.602+00:00",
    "payload": {
      "created_at": "2025-10-08T17:16:08.436941",
      "custom_code": "25565",
      "delivery_status": "delivered",
      "extension": null,
      "failed_attempts": 0,
      "id": "010d9dee-d86d-47d0-8d6c-20c0f95a79ec",
      "mccmnc": null,
      "phone_number": "+13125000000",
      "profile_id": "49000192-1bdb-c56f-3de7-e008ef6da16b",
      "record_type": "verification",
      "status": "pending",
      "timeout_secs": null,
      "type": "sms",
      "updated_at": "2025-10-08T17:16:09.592765"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
  }
}

Delivery statuses

Delivery Status Description sent The verification has been sent to the upstream provider. delivered The upstream provider has confirmed delivery of the verification. sending_failed Telnyx has failed to send the verification to the upstream provider. Please reach out to our support if you have received this status. delivery_failed The upstream provider has failed to send the verification to the receiver. Please reach out to our support if you have received this status. delivery_unconfirmed There is no indication whether or not the verification has reached the receiver. Please reach out to our support if you have received this status

Real-time verification status updates

Telnyx Verify now supports webhooks for instant verification status notifications, eliminating the need to poll the API for verification completion.

Benefits

Eliminates polling - No need to repeatedly check verification status through API calls.
Event-driven workflow - React immediately to verification state changes in real-time.
Faster user experience - Process verification completions instantly without delays.
Improved efficiency - Reduces server load and unnecessary API requests.

Configure webhooks on your Verify profile to receive real-time updates when verifications complete. For specific webhook event types, payload structures, and configuration details, refer to the Telnyx API documentation or contact Telnyx support.

Telnyx Webhook IPs

If you use an ACL or Firewall on your network, make sure you whitelist the following subnet(s): 192.76.120.192/27

Security Best Practices

Source: https://developers.telnyx.com/docs/identity/verify/security-best-practices.md

Verification flows are a high-value target for attackers. SMS pumping, toll fraud, brute-force code guessing, and social engineering can cost you money and compromise user accounts. This guide covers practical defenses you should implement alongside Telnyx Verify.

Threat overview

Threat	Description	Impact
SMS pumping	Attackers trigger thousands of SMS verifications to premium-rate numbers	Inflated costs, sometimes $10K+ per incident
Toll fraud (IRSF)	Exploiting call verification to generate revenue on premium international numbers	Per-minute charges on fraudulent calls
Brute-force attacks	Systematically guessing verification codes	Account takeover
Code interception	SIM swapping, SS7 attacks, malware intercepting SMS	Account compromise
Enumeration	Using verification endpoints to check if phone numbers exist in your system	Privacy leak, targeted attacks

Rate limiting

Rate limiting is your first line of defense against abuse. Apply limits at multiple layers.

Per-phone-number limits

Restrict how many verification attempts a single phone number can trigger within a time window.

Node

import { RateLimiterMemory } from 'rate-limiter-flexible';

// Max 3 verification requests per phone number per 10 minutes
const phoneLimiter = new RateLimiterMemory({
  points: 3,
  duration: 600, // 10 minutes
});

async function requestVerification(phoneNumber) {
  try {
    await phoneLimiter.consume(phoneNumber);
    // Proceed with Telnyx Verify API call
  } catch (rejRes) {
    const retryAfter = Math.ceil(rejRes.msBeforeNext / 1000);
    throw new Error(`Too many attempts. Try again in ${retryAfter} seconds.`);
  }
}

Python

from datetime import datetime, timedelta

# Simple in-memory rate limiter (use Redis in production)
verification_attempts = {}

def check_rate_limit(phone_number, max_attempts=3, window_minutes=10):
    now = datetime.utcnow()
    cutoff = now - timedelta(minutes=window_minutes)

    # Clean old attempts
    attempts = verification_attempts.get(phone_number, [])
    attempts = [t for t in attempts if t > cutoff]

    if len(attempts) >= max_attempts:
        raise Exception(f"Too many attempts. Try again later.")

    attempts.append(now)
    verification_attempts[phone_number] = attempts
    return True

package main

import (
  "fmt"
  "sync"
  "time"
)

type RateLimiter struct {
  mu       sync.Mutex
  attempts map[string][]time.Time
  max      int
  window   time.Duration
}

func NewRateLimiter(max int, window time.Duration) *RateLimiter {
  return &RateLimiter{
    attempts: make(map[string][]time.Time),
    max:      max,
    window:   window,
  }
}

func (rl *RateLimiter) Allow(key string) error {
  rl.mu.Lock()
  defer rl.mu.Unlock()

  cutoff := time.Now().Add(-rl.window)
  var valid []time.Time
  for _, t := range rl.attempts[key] {
    if t.After(cutoff) {
      valid = append(valid, t)
    }
  }

  if len(valid) >= rl.max {
    return fmt.Errorf("too many attempts, try again later")
  }

  rl.attempts[key] = append(valid, time.Now())
  return nil
}

Per-IP address limits

Prevent a single IP from triggering verifications for many different numbers (a hallmark of SMS pumping):

Node

// Max 10 verification requests per IP per hour
const ipLimiter = new RateLimiterMemory({
  points: 10,
  duration: 3600,
});

app.post('/verify/request', async (req, res) => {
  const clientIp = req.ip;
  try {
    await ipLimiter.consume(clientIp);
    await phoneLimiter.consume(req.body.phone_number);
    // Proceed with verification
  } catch {
    res.status(429).json({ error: 'Too many requests' });
  }
});

Python

from flask import Flask, request, jsonify
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address

app = Flask(__name__)
limiter = Limiter(app=app, key_func=get_remote_address)

@app.route("/verify/request", methods=["POST"])
@limiter.limit("10 per hour")
def request_verification():
    phone_number = request.json["phone_number"]
    check_rate_limit(phone_number)
    # Proceed with Telnyx Verify API call
    return jsonify(success=True)

Recommended limits

Scope	Limit	Window
Per phone number	3 attempts	10 minutes
Per phone number	5 attempts	1 hour
Per IP address	10 attempts	1 hour
Per account/session	5 attempts	1 hour
Global (all numbers)	Monitor for spikes	Continuous

SMS pumping prevention

SMS pumping is the most costly fraud vector for verification flows. Attackers abuse your send endpoint to generate SMS revenue on number ranges they control.

Detection signals

Watch for these patterns:

Sequential numbers — Verification requests for +1234500001, +1234500002, +1234500003…
Unusual country codes — Spike in verifications to countries you don’t serve
High failure rate — Many verifications triggered but never completed
Burst traffic — Sudden spike in verification requests from a single source

Defenses

Configure whitelisted_destinations on your Verify profile to only allow countries where your users are:

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "whitelisted_destinations": ["US", "CA", "GB"]
    }
  }'

Don’t expose your verification endpoint to unauthenticated users. Require at least a session or account to trigger a verification. Place a CAPTCHA (reCAPTCHA, hCaptcha, Turnstile) before the phone number input to block automated submissions. Set up alerts for unusual verification volume:

// Track verification requests per minute
const verifyCount = new Map();

function trackVerification() {
  const minute = Math.floor(Date.now() / 60000);
  verifyCount.set(minute, (verifyCount.get(minute) || 0) + 1);

  if (verifyCount.get(minute) > 100) {
    // Alert: possible SMS pumping attack
    alertOps('Verification spike detected: ' + verifyCount.get(minute) + '/min');
  }
}

Code security

Use appropriate code length

Longer codes are harder to brute-force but harder for users to enter. Balance security and usability:

Code Length	Combinations	Brute-force time (3 attempts/min)	Recommendation
4 digits	10,000	~55 hours	Low security only
5 digits	100,000	~23 days	Default — good balance
6 digits	1,000,000	~231 days	High security applications

Configure code length in your Verify profile:

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "code_length": 6
    }
  }'

Set appropriate timeouts

Short timeouts reduce the window for brute-force attacks:

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "default_timeout_secs": 300
    },
    "call": {
      "default_timeout_secs": 300
    }
  }'

A 5-minute timeout (300 seconds) works well for most applications. Shorter timeouts (120s) add security but may frustrate users on slow networks.

Limit verification attempts

Lock out after too many failed code entries to prevent brute-force:

Node

const failedAttempts = new Map();

async function verifyCode(phoneNumber, code) {
  const attempts = failedAttempts.get(phoneNumber) || 0;

  if (attempts >= 5) {
    throw new Error('Too many failed attempts. Request a new code.');
  }

  const response = await fetch(
    `https://api.telnyx.com/v2/verifications/by_phone_number/${phoneNumber}/actions/verify`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.TELNYX_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ code, verify_profile_id: PROFILE_ID }),
    }
  );
  const result = await response.json();

  if (result.data.response_code === 'accepted') {
    failedAttempts.delete(phoneNumber);
    return true;
  }

  failedAttempts.set(phoneNumber, attempts + 1);
  return false;
}

Python

import requests
import os

failed_attempts = {}  # Use Redis in production

def verify_code(phone_number, code, profile_id):
    attempts = failed_attempts.get(phone_number, 0)

    if attempts >= 5:
        raise Exception("Too many failed attempts. Request a new code.")

    response = requests.post(
        f"https://api.telnyx.com/v2/verifications/by_phone_number/{phone_number}/actions/verify",
        headers={"Authorization": f"Bearer {os.environ['TELNYX_API_KEY']}"},
        json={"code": code, "verify_profile_id": profile_id},
    )
    result = response.json()

    if result["data"]["response_code"] == "accepted":
        failed_attempts.pop(phone_number, None)
        return True

    failed_attempts[phone_number] = attempts + 1
    return False

Prevent number enumeration

Don’t reveal whether a phone number exists in your system through verification responses: ❌ Vulnerable — reveals whether the number is registered:

{ "error": "No account found for this phone number" }

✅ Secure — same response regardless:

{ "message": "If this number is registered, you'll receive a verification code." }

Always return a consistent response and send the verification (or silently drop it) regardless of whether the number exists in your system.

Channel fallback strategy

Use multiple verification channels to improve delivery and security: Start with SMS verification — widest reach and fastest delivery. If SMS isn’t delivered within 30 seconds, offer a voice call option. This helps users on networks with delayed SMS delivery. For supported markets, flashcall verification (where the phone number itself is the code) provides instant verification with no user input required. Configure all three channels on your Verify profile:

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "whitelisted_destinations": ["US", "CA"],
      "default_timeout_secs": 300,
      "code_length": 6
    },
    "call": {
      "default_timeout_secs": 300
    },
    "flashcall": {
      "default_timeout_secs": 300
    }
  }'

Webhook security for Verify

Secure your verification webhook endpoint to prevent spoofed delivery notifications:

Allowlist Telnyx IPs — Only accept webhooks from 192.76.120.192/27
Use HTTPS — Never use plain HTTP for webhook endpoints
Validate payload structure — Check for expected fields before processing
Don’t trust client-side status — Always verify through webhooks or API, never trust client-reported verification status

Node

import { createServer } from 'http';
import { networkInterfaces } from 'os';

const TELNYX_WEBHOOK_CIDR = '192.76.120.192/27';

function isFromTelnyx(ip) {
  // In production, use a proper CIDR matching library
  const parts = ip.split('.').map(Number);
  return parts[0] === 192 && parts[1] === 76 &&
         parts[2] === 120 && parts[3] >= 192 && parts[3] <= 223;
}

app.post('/webhooks/verify', (req, res) => {
  const clientIp = req.headers['x-forwarded-for']?.split(',')[0] || req.ip;

  if (!isFromTelnyx(clientIp)) {
    console.warn(`Rejected webhook from unauthorized IP: ${clientIp}`);
    return res.sendStatus(403);
  }

  // Process webhook
  const event = req.body.data;
  if (event.event_type === 'verify.delivered') {
    console.log(`Verification delivered to ${event.payload.phone_number}`);
  }

  res.sendStatus(200);
});

Python

import ipaddress
from flask import Flask, request, jsonify

TELNYX_WEBHOOK_SUBNET = ipaddress.ip_network("192.76.120.192/27")

@app.route("/webhooks/verify", methods=["POST"])
def handle_verify_webhook():
    client_ip = ipaddress.ip_address(
        request.headers.get("X-Forwarded-For", request.remote_addr).split(",")[0].strip()
    )

    if client_ip not in TELNYX_WEBHOOK_SUBNET:
        return jsonify(error="Forbidden"), 403

    event = request.json["data"]
    if event["event_type"] == "verify.delivered":
        print(f"Verification delivered to {event['payload']['phone_number']}")

    return jsonify(success=True), 200

Security checklist

Use this checklist when implementing Telnyx Verify in production:

Next steps

Set up your first verification flow Brand your verification messages Receive real-time verification status updates Advanced fraud prevention strategies

Rate Limiting & Fraud Prevention

Source: https://developers.telnyx.com/docs/identity/verify/rate-limiting-fraud-prevention.md

This guide goes deep on the operational side of protecting your Telnyx Verify integration — server-side rate limiting architectures, geo-fencing, anomaly detection, cost controls, and incident response. For foundational security concepts, see the Security Best Practices guide.

Architecture overview

A robust fraud prevention system layers multiple defenses:

User Request → CAPTCHA → IP Rate Limit → Phone Rate Limit → Geo-fence → Anomaly Check → Telnyx Verify API

Each layer catches different attack patterns. No single defense is sufficient on its own.

Server-side rate limiting with Redis

Production rate limiting requires a distributed store. These examples use Redis for shared state across multiple application instances.

Sliding window rate limiter

Node

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

/**
 * Sliding window rate limiter using Redis sorted sets.
 * @param {string} key - Rate limit key (e.g., phone number or IP)
 * @param {number} maxRequests - Maximum requests allowed
 * @param {number} windowMs - Time window in milliseconds
 * @returns {Promise<{allowed: boolean, remaining: number, retryAfterMs: number}>}
 */
async function checkRateLimit(key, maxRequests, windowMs) {
  const now = Date.now();
  const windowStart = now - windowMs;
  const redisKey = `ratelimit:${key}`;

  const pipeline = redis.pipeline();
  pipeline.zremrangebyscore(redisKey, 0, windowStart);  // Remove expired
  pipeline.zcard(redisKey);                              // Count current
  pipeline.zadd(redisKey, now, `${now}-${Math.random()}`); // Add this request
  pipeline.expire(redisKey, Math.ceil(windowMs / 1000)); // Set TTL

  const results = await pipeline.exec();
  const currentCount = results[1][1];

  if (currentCount >= maxRequests) {
    // Remove the entry we just added
    await redis.zremrangebyscore(redisKey, now, now);
    const oldestEntry = await redis.zrange(redisKey, 0, 0, 'WITHSCORES');
    const retryAfterMs = oldestEntry.length > 1
      ? windowMs - (now - Number(oldestEntry[1]))
      : windowMs;

    return { allowed: false, remaining: 0, retryAfterMs };
  }

  return { allowed: true, remaining: maxRequests - currentCount - 1, retryAfterMs: 0 };
}

// Usage: Multi-layer rate limiting
async function handleVerificationRequest(req) {
  const phone = req.body.phone_number;
  const ip = req.ip;
  const userId = req.user?.id;

  // Layer 1: IP rate limit (10/hour)
  const ipCheck = await checkRateLimit(`ip:${ip}`, 10, 3600000);
  if (!ipCheck.allowed) {
    return { status: 429, retryAfter: ipCheck.retryAfterMs };
  }

  // Layer 2: Phone rate limit (3/10min)
  const phoneCheck = await checkRateLimit(`phone:${phone}`, 3, 600000);
  if (!phoneCheck.allowed) {
    return { status: 429, retryAfter: phoneCheck.retryAfterMs };
  }

  // Layer 3: User rate limit (5/hour)
  if (userId) {
    const userCheck = await checkRateLimit(`user:${userId}`, 5, 3600000);
    if (!userCheck.allowed) {
      return { status: 429, retryAfter: userCheck.retryAfterMs };
    }
  }

  // All checks passed — send verification
  return await sendVerification(phone);
}

Python

import time
import math
import redis
import os
import random

r = redis.Redis.from_url(os.environ.get("REDIS_URL", "redis://localhost:6379"))

def check_rate_limit(key: str, max_requests: int, window_seconds: int) -> dict:
    """Sliding window rate limiter using Redis sorted sets."""
    now = time.time()
    window_start = now - window_seconds
    redis_key = f"ratelimit:{key}"

    pipe = r.pipeline()
    pipe.zremrangebyscore(redis_key, 0, window_start)
    pipe.zcard(redis_key)
    pipe.zadd(redis_key, {f"{now}-{random.random()}": now})
    pipe.expire(redis_key, window_seconds + 1)
    results = pipe.execute()

    current_count = results[1]

    if current_count >= max_requests:
        r.zremrangebyscore(redis_key, now, now)
        oldest = r.zrange(redis_key, 0, 0, withscores=True)
        retry_after = window_seconds - (now - oldest[0][1]) if oldest else window_seconds
        return {"allowed": False, "remaining": 0, "retry_after_seconds": math.ceil(retry_after)}

    return {"allowed": True, "remaining": max_requests - current_count - 1, "retry_after_seconds": 0}

def handle_verification_request(phone_number: str, ip: str, user_id: str = None):
    # Layer 1: IP rate limit (10/hour)
    ip_check = check_rate_limit(f"ip:{ip}", 10, 3600)
    if not ip_check["allowed"]:
        return {"error": "Too many requests", "retry_after": ip_check["retry_after_seconds"]}

    # Layer 2: Phone rate limit (3/10min)
    phone_check = check_rate_limit(f"phone:{phone_number}", 3, 600)
    if not phone_check["allowed"]:
        return {"error": "Too many attempts for this number", "retry_after": phone_check["retry_after_seconds"]}

    # Layer 3: User rate limit (5/hour)
    if user_id:
        user_check = check_rate_limit(f"user:{user_id}", 5, 3600)
        if not user_check["allowed"]:
            return {"error": "Too many requests", "retry_after": user_check["retry_after_seconds"]}

    return send_verification(phone_number)

Ruby

require "redis"

redis = Redis.new(url: ENV["REDIS_URL"] || "redis://localhost:6379")

def check_rate_limit(redis, key, max_requests, window_seconds)
  now = Time.now.to_f
  window_start = now - window_seconds
  redis_key = "ratelimit:#{key}"

  redis.pipelined do |pipe|
    pipe.zremrangebyscore(redis_key, 0, window_start)
    pipe.zcard(redis_key)
    pipe.zadd(redis_key, now, "#{now}-#{rand}")
    pipe.expire(redis_key, window_seconds + 1)
  end => [_, current_count, _, _]

  if current_count >= max_requests
    redis.zremrangebyscore(redis_key, now, now)
    oldest = redis.zrange(redis_key, 0, 0, with_scores: true)
    retry_after = oldest.any? ? window_seconds - (now - oldest[0][1]) : window_seconds
    { allowed: false, remaining: 0, retry_after: retry_after.ceil }
  else
    { allowed: true, remaining: max_requests - current_count - 1, retry_after: 0 }
  end
end

package ratelimit

import (
  "context"
  "fmt"
  "math/rand"
  "time"

  "github.com/redis/go-redis/v9"
)

type Result struct {
  Allowed      bool
  Remaining    int
  RetryAfterMs int64
}

func CheckRateLimit(ctx context.Context, rdb *redis.Client, key string, maxReqs int, window time.Duration) (*Result, error) {
  now := time.Now()
  windowStart := now.Add(-window)
  redisKey := fmt.Sprintf("ratelimit:%s", key)

  pipe := rdb.Pipeline()
  pipe.ZRemRangeByScore(ctx, redisKey, "0", fmt.Sprintf("%f", float64(windowStart.UnixMilli())))
  countCmd := pipe.ZCard(ctx, redisKey)
  member := fmt.Sprintf("%d-%f", now.UnixMilli(), rand.Float64())
  pipe.ZAdd(ctx, redisKey, redis.Z{Score: float64(now.UnixMilli()), Member: member})
  pipe.Expire(ctx, redisKey, window+time.Second)
  _, err := pipe.Exec(ctx)
  if err != nil {
    return nil, err
  }

  count := countCmd.Val()
  if count >= int64(maxReqs) {
    rdb.ZRem(ctx, redisKey, member)
    return &Result{Allowed: false, Remaining: 0, RetryAfterMs: window.Milliseconds()}, nil
  }

  return &Result{Allowed: true, Remaining: maxReqs - int(count) - 1, RetryAfterMs: 0}, nil
}

Geo-fencing

Restrict verifications to countries where your service operates. This is the single most effective defense against SMS pumping.

Configure on Verify profile

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "whitelisted_destinations": ["US", "CA", "GB", "AU"]
    }
  }'

Application-level geo-validation

Add server-side validation before calling the API as a defense-in-depth measure:

Node

import { parsePhoneNumber } from 'libphonenumber-js';

const ALLOWED_COUNTRIES = new Set(['US', 'CA', 'GB', 'AU']);

function validatePhoneCountry(phoneNumber) {
  const parsed = parsePhoneNumber(phoneNumber);
  if (!parsed || !parsed.country) {
    throw new Error('Invalid phone number');
  }
  if (!ALLOWED_COUNTRIES.has(parsed.country)) {
    throw new Error('Verification not available in this region');
  }
  return parsed.country;
}

Python

import phonenumbers

ALLOWED_COUNTRIES = {"US", "CA", "GB", "AU"}

def validate_phone_country(phone_number: str) -> str:
    parsed = phonenumbers.parse(phone_number)
    country = phonenumbers.region_code_for_number(parsed)
    if country not in ALLOWED_COUNTRIES:
        raise ValueError("Verification not available in this region")
    return country

High-risk country codes

These country codes are frequently targeted for SMS pumping and toll fraud. Block or add extra scrutiny:

Code	Country	Risk
+232	Sierra Leone	SMS pumping
+225	Côte d’Ivoire	SMS pumping
+233	Ghana	SMS pumping
+234	Nigeria	Mixed (legitimate + fraud)
+260	Zambia	SMS pumping
+256	Uganda	SMS pumping
+880	Bangladesh	Toll fraud
+855	Cambodia	Toll fraud
+856	Laos	Toll fraud
+960	Maldives	Toll fraud
+592	Guyana	Toll fraud

Note: These are statistical patterns, not blanket rules. If you serve users in these countries, implement stronger rate limiting rather than blocking.

Anomaly detection

Build automated detection for suspicious patterns beyond simple rate limits.

Conversion rate monitoring

A healthy verification flow has a 60-80% conversion rate (codes sent vs. codes verified). A rate below 20% may indicate an attack.

Node

class ConversionMonitor {
  constructor(redis, alertCallback) {
    this.redis = redis;
    this.alertCallback = alertCallback;
  }

  async trackSent(phoneNumber) {
    const hour = Math.floor(Date.now() / 3600000);
    await this.redis.incr(`verify:sent:${hour}`);
    await this.redis.expire(`verify:sent:${hour}`, 7200);
  }

  async trackVerified(phoneNumber) {
    const hour = Math.floor(Date.now() / 3600000);
    await this.redis.incr(`verify:verified:${hour}`);
    await this.redis.expire(`verify:verified:${hour}`, 7200);
  }

  async checkConversionRate() {
    const hour = Math.floor(Date.now() / 3600000);
    const sent = parseInt(await this.redis.get(`verify:sent:${hour}`)) || 0;
    const verified = parseInt(await this.redis.get(`verify:verified:${hour}`)) || 0;

    if (sent < 10) return; // Too few samples

    const rate = verified / sent;
    if (rate < 0.2) {
      this.alertCallback({
        message: `Low verification conversion rate: ${(rate * 100).toFixed(1)}%`,
        sent,
        verified,
        hour: new Date(hour * 3600000).toISOString(),
      });
    }
  }
}

Python

import time
import redis as redis_lib

class ConversionMonitor:
    def __init__(self, redis_client, alert_callback):
        self.redis = redis_client
        self.alert = alert_callback

    def _hour_key(self):
        return int(time.time() // 3600)

    def track_sent(self):
        hour = self._hour_key()
        self.redis.incr(f"verify:sent:{hour}")
        self.redis.expire(f"verify:sent:{hour}", 7200)

    def track_verified(self):
        hour = self._hour_key()
        self.redis.incr(f"verify:verified:{hour}")
        self.redis.expire(f"verify:verified:{hour}", 7200)

    def check_conversion_rate(self):
        hour = self._hour_key()
        sent = int(self.redis.get(f"verify:sent:{hour}") or 0)
        verified = int(self.redis.get(f"verify:verified:{hour}") or 0)

        if sent < 10:
            return

        rate = verified / sent
        if rate < 0.2:
            self.alert({
                "message": f"Low verification conversion rate: {rate:.1%}",
                "sent": sent,
                "verified": verified,
            })

Sequential number detection

SMS pumping often uses sequential phone numbers. Detect and block this pattern:

function detectSequentialNumbers(recentNumbers, threshold = 5) {
  if (recentNumbers.length < threshold) return false;

  // Sort by numeric value
  const sorted = recentNumbers
    .map(n => BigInt(n.replace(/\D/g, '')))
    .sort((a, b) => (a < b ? -1 : 1));

  // Check for sequences
  let sequential = 1;
  for (let i = 1; i < sorted.length; i++) {
    if (sorted[i] - sorted[i - 1] <= 3n) {
      sequential++;
      if (sequential >= threshold) return true;
    } else {
      sequential = 1;
    }
  }

  return false;
}

Cost controls

Set spend alerts

Monitor your Telnyx account spending and set alerts at the account level through the Telnyx Portal billing settings.

Implement circuit breakers

Automatically disable verifications when anomalies are detected:

class VerificationCircuitBreaker {
  constructor(redis, maxPerHour = 500) {
    this.redis = redis;
    this.maxPerHour = maxPerHour;
    this.tripped = false;
  }

  async canSend() {
    if (this.tripped) return false;

    const hour = Math.floor(Date.now() / 3600000);
    const count = parseInt(await this.redis.get(`verify:total:${hour}`)) || 0;

    if (count >= this.maxPerHour) {
      this.tripped = true;
      // Alert operations team
      console.error(`Circuit breaker tripped: ${count} verifications in current hour`);
      return false;
    }

    await this.redis.incr(`verify:total:${hour}`);
    await this.redis.expire(`verify:total:${hour}`, 7200);
    return true;
  }

  reset() {
    this.tripped = false;
  }
}

Incident response

When you detect a fraud attack in progress: Stop all verification sends to limit financial damage. Look at the destination countries, IP addresses, and phone number patterns in your logs. Remove affected countries from your Verify profile’s whitelisted_destinations. Reduce rate limits, add CAPTCHA if not present, and re-enable verifications gradually. Report the incident to Telnyx Support for investigation and potential charge reversal.

Configuration reference

Summary of all Verify profile settings relevant to fraud prevention:

Setting	Endpoint	Purpose
`whitelisted_destinations`	`PATCH /v2/verify_profiles/{id}`	Restrict SMS to specific countries
`code_length`	`PATCH /v2/verify_profiles/{id}`	Set verification code length (4-10)
`default_timeout_secs`	`PATCH /v2/verify_profiles/{id}`	Expiration time for codes

# Example: Production-hardened Verify profile
curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "whitelisted_destinations": ["US", "CA"],
      "default_timeout_secs": 300,
      "code_length": 6
    },
    "call": {
      "default_timeout_secs": 300
    }
  }'

Next steps

Foundational security concepts for Verify Get started with Telnyx Verify Real-time verification delivery status Brand your verification messages

API Reference (Identity)

Number Lookup

Lookup phone number data: Returns information about the provided phone number.

Verify

Trigger Call verification: Starts a verification for the specified phone number and delivers its code in a voice call using the selected Verify profile. Returns the pending verification…
Trigger Flash call verification: Starts a verification for the specified phone number and places a brief call with the code embedded in the caller ID. Returns the pending verification record.
Trigger SMS verification: Starts a verification for the specified phone number and sends its code by SMS using the selected Verify profile. Returns the pending verification record.
Trigger WhatsApp verification: Starts a verification for the specified phone number and sends its code over WhatsApp using the selected Verify profile. Returns the pending verification recor…
Retrieve verification: Returns the verification identified by ID, including its channel, phone number, Verify profile, timeout, and current status.
Verify verification code by ID: Checks the supplied code, or the supplied status for a custom-code verification, against the verification identified by ID. The response indicates whether the…
List verifications by phone number: Returns a paginated list of verifications associated with the specified phone number.
Verify verification code by phone number: Submits a verification code for the specified phone number and Verify profile. The response indicates whether the code was accepted or rejected.
List all Verify profiles: Gets a paginated list of Verify profiles.
Create a Verify profile: Creates a new Verify profile to associate verifications with.
Delete Verify profile: Deletes the specified Verify profile and returns the deleted profile record.
Retrieve Verify profile: Gets a single Verify profile.
Update Verify profile: Updates the specified Verify profile’s name, webhook destinations, language, daily spend limits, or channel-specific settings. Returns the updated profile.
Retrieve Verify profile message templates: List all Verify profile message templates.
Create message template: Create a new Verify profile message template.
Update message template: Update an existing Verify profile message template.

⌘I

​Telnyx Numbers: Identity — Full Documentation

​Number Lookup

​Number lookup using Telnyx APIs

​Lookup: Carrier and caller name

​cURL

​Basic number lookup example

​Retrieving caller name and carrier

​Python

​Basic number lookup example

​Retrieving caller name and carrier

​Node

​Basic number lookup example

​Retrieving caller name and carrier

​Ruby

​Basic number lookup example

​Retrieving caller name and carrier

​Verify

​Telnyx verify quickstart

​Prerequisites

​Methods of verification

​Create a verify profile

​Select a message template

​Example response

​Create a verify profile

​Example response

​Trigger a verification request

​Example response (all methods)

​Choosing the right verification method

​Verify a 2FA code

​Example response

​Next steps

​DTMF confirmation

​Flow

​Use cases

​Create a verify profile

​Trigger verification

​Response

​Handle the result

​Accepted (digit 1 pressed)

​Failed (wrong digit, timeout, or call failure)

​Polling alternative

​Complete example

​Verification type comparison

​Troubleshooting

​Next steps

​Custom templates

​Overview

​When to use custom templates

​Template variables

​Creating custom templates

​Create a custom template

​Example response

​Real-world template examples

​E-commerce and retail

​Banking and finance

​Healthcare and telemedicine

​Social media and gaming

​Delivery and logistics

​Travel and hospitality

​Using custom templates in verify profiles

​Example: Create verify profile with custom template

​Updating custom templates

​Update a template

​Example response

​Best practices

​Keep messages concise

​Include security warnings

​Test before production

​Follow compliance guidelines

​Consider localization

​Next steps

​Webhooks

​Verify delivery status updates

​Delivery status Payload

​Delivery statuses

​Real-time verification status updates

​Benefits

​Telnyx Webhook IPs

​Security Best Practices

​Threat overview

Telnyx Numbers: Identity — Full Documentation

Number Lookup

Number lookup using Telnyx APIs

Lookup: Carrier and caller name

cURL

Basic number lookup example

Retrieving caller name and carrier

Python

Basic number lookup example

Retrieving caller name and carrier

Node

Basic number lookup example

Retrieving caller name and carrier

Ruby

Basic number lookup example

Retrieving caller name and carrier

Verify

Telnyx verify quickstart

Prerequisites

Methods of verification

Create a verify profile

Select a message template

Example response

Create a verify profile

Example response

Trigger a verification request

Example response (all methods)

Choosing the right verification method

Verify a 2FA code

Example response

Next steps

DTMF confirmation

Flow

Use cases

Create a verify profile

Trigger verification

Response

Handle the result

Accepted (digit `1` pressed)

Failed (wrong digit, timeout, or call failure)

Polling alternative

Complete example

Verification type comparison

Troubleshooting

Next steps

Custom templates

Overview

When to use custom templates

Template variables

Creating custom templates

Create a custom template

Example response

Real-world template examples

E-commerce and retail

Banking and finance

Healthcare and telemedicine

Social media and gaming

Delivery and logistics

Travel and hospitality

Using custom templates in verify profiles

Example: Create verify profile with custom template

Updating custom templates

Update a template

Example response

Best practices

Keep messages concise

Include security warnings

Test before production

Follow compliance guidelines

Consider localization

Next steps

Webhooks

Verify delivery status updates

Delivery status Payload

Delivery statuses

Real-time verification status updates

Benefits

Telnyx Webhook IPs

Security Best Practices

Threat overview