Submit or resubmit a toll-free number for verification (TFV)

curl --request POST \
  --url https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "use_case": "Customer Care",
  "use_case_summary": "Appointment reminders and order-status updates for customers who opted in at checkout.",
  "sample_messages": [
    "Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out."
  ],
  "business_name": "Acme Co",
  "business_website": "https://acme.example.com",
  "ein": "12-3456789",
  "contact_email": "compliance@acme.example.com",
  "contact_phone": "+14155550123",
  "opt_in_type": "WEB_FORM",
  "opt_in_image_urls": [
    "https://acme.example.com/opt-in-proof.png"
  ],
  "message_volume": "10,000"
}
'

import requests

url = "https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit"

payload = {
    "use_case": "Customer Care",
    "use_case_summary": "Appointment reminders and order-status updates for customers who opted in at checkout.",
    "sample_messages": ["Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out."],
    "business_name": "Acme Co",
    "business_website": "https://acme.example.com",
    "ein": "12-3456789",
    "contact_email": "compliance@acme.example.com",
    "contact_phone": "+14155550123",
    "opt_in_type": "WEB_FORM",
    "opt_in_image_urls": ["https://acme.example.com/opt-in-proof.png"],
    "message_volume": "10,000"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    use_case: 'Customer Care',
    use_case_summary: 'Appointment reminders and order-status updates for customers who opted in at checkout.',
    sample_messages: ['Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.'],
    business_name: 'Acme Co',
    business_website: 'https://acme.example.com',
    ein: '12-3456789',
    contact_email: 'compliance@acme.example.com',
    contact_phone: '+14155550123',
    opt_in_type: 'WEB_FORM',
    opt_in_image_urls: ['https://acme.example.com/opt-in-proof.png'],
    message_volume: '10,000'
  })
};

fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'use_case' => 'Customer Care',
    'use_case_summary' => 'Appointment reminders and order-status updates for customers who opted in at checkout.',
    'sample_messages' => [
        'Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.'
    ],
    'business_name' => 'Acme Co',
    'business_website' => 'https://acme.example.com',
    'ein' => '12-3456789',
    'contact_email' => 'compliance@acme.example.com',
    'contact_phone' => '+14155550123',
    'opt_in_type' => 'WEB_FORM',
    'opt_in_image_urls' => [
        'https://acme.example.com/opt-in-proof.png'
    ],
    'message_volume' => '10,000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit"

	payload := strings.NewReader("{\n  \"use_case\": \"Customer Care\",\n  \"use_case_summary\": \"Appointment reminders and order-status updates for customers who opted in at checkout.\",\n  \"sample_messages\": [\n    \"Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.\"\n  ],\n  \"business_name\": \"Acme Co\",\n  \"business_website\": \"https://acme.example.com\",\n  \"ein\": \"12-3456789\",\n  \"contact_email\": \"compliance@acme.example.com\",\n  \"contact_phone\": \"+14155550123\",\n  \"opt_in_type\": \"WEB_FORM\",\n  \"opt_in_image_urls\": [\n    \"https://acme.example.com/opt-in-proof.png\"\n  ],\n  \"message_volume\": \"10,000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"use_case\": \"Customer Care\",\n  \"use_case_summary\": \"Appointment reminders and order-status updates for customers who opted in at checkout.\",\n  \"sample_messages\": [\n    \"Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.\"\n  ],\n  \"business_name\": \"Acme Co\",\n  \"business_website\": \"https://acme.example.com\",\n  \"ein\": \"12-3456789\",\n  \"contact_email\": \"compliance@acme.example.com\",\n  \"contact_phone\": \"+14155550123\",\n  \"opt_in_type\": \"WEB_FORM\",\n  \"opt_in_image_urls\": [\n    \"https://acme.example.com/opt-in-proof.png\"\n  ],\n  \"message_volume\": \"10,000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"use_case\": \"Customer Care\",\n  \"use_case_summary\": \"Appointment reminders and order-status updates for customers who opted in at checkout.\",\n  \"sample_messages\": [\n    \"Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.\"\n  ],\n  \"business_name\": \"Acme Co\",\n  \"business_website\": \"https://acme.example.com\",\n  \"ein\": \"12-3456789\",\n  \"contact_email\": \"compliance@acme.example.com\",\n  \"contact_phone\": \"+14155550123\",\n  \"opt_in_type\": \"WEB_FORM\",\n  \"opt_in_image_urls\": [\n    \"https://acme.example.com/opt-in-proof.png\"\n  ],\n  \"message_volume\": \"10,000\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "phoneNumberId": "<string>",
    "phoneNumber": "<string>",
    "tfvStatus": "not_submitted",
    "tfvProvider": "<string>",
    "tfvProviderSubmissionId": "<string>",
    "tfvSubmittedAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

Numbers

Submit or resubmit a toll-free number for verification (TFV)

Submit (or resubmit) the Toll-Free Verification form for a toll-free DID so the carrier can approve it for messaging — without an approved TFV, US / CA toll-free traffic is throttled or blocked with 30032 errors. Supply the messaging use case, a use-case summary, 1–5 sample messages, business identity (name, website, and either an EIN or a business registration number + ISO country), a contact email and E.164 phone, the opt-in type with 1–5 opt-in proof image URLs, and the expected monthly message volume. Samples are content-linted before submission, so disallowed-vertical content is rejected up front (422) instead of after a multi-day carrier review; political use cases additionally require a Campaign Verify token. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot submit attestation against another org’s DID. Scoped on numbers:write (owner / admin).

POST

api

numbers

{id}

tfv-submit

Submit or resubmit a toll-free number for verification (TFV)

curl --request POST \
  --url https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "use_case": "Customer Care",
  "use_case_summary": "Appointment reminders and order-status updates for customers who opted in at checkout.",
  "sample_messages": [
    "Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out."
  ],
  "business_name": "Acme Co",
  "business_website": "https://acme.example.com",
  "ein": "12-3456789",
  "contact_email": "compliance@acme.example.com",
  "contact_phone": "+14155550123",
  "opt_in_type": "WEB_FORM",
  "opt_in_image_urls": [
    "https://acme.example.com/opt-in-proof.png"
  ],
  "message_volume": "10,000"
}
'

import requests

url = "https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit"

payload = {
    "use_case": "Customer Care",
    "use_case_summary": "Appointment reminders and order-status updates for customers who opted in at checkout.",
    "sample_messages": ["Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out."],
    "business_name": "Acme Co",
    "business_website": "https://acme.example.com",
    "ein": "12-3456789",
    "contact_email": "compliance@acme.example.com",
    "contact_phone": "+14155550123",
    "opt_in_type": "WEB_FORM",
    "opt_in_image_urls": ["https://acme.example.com/opt-in-proof.png"],
    "message_volume": "10,000"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    use_case: 'Customer Care',
    use_case_summary: 'Appointment reminders and order-status updates for customers who opted in at checkout.',
    sample_messages: ['Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.'],
    business_name: 'Acme Co',
    business_website: 'https://acme.example.com',
    ein: '12-3456789',
    contact_email: 'compliance@acme.example.com',
    contact_phone: '+14155550123',
    opt_in_type: 'WEB_FORM',
    opt_in_image_urls: ['https://acme.example.com/opt-in-proof.png'],
    message_volume: '10,000'
  })
};

fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'use_case' => 'Customer Care',
    'use_case_summary' => 'Appointment reminders and order-status updates for customers who opted in at checkout.',
    'sample_messages' => [
        'Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.'
    ],
    'business_name' => 'Acme Co',
    'business_website' => 'https://acme.example.com',
    'ein' => '12-3456789',
    'contact_email' => 'compliance@acme.example.com',
    'contact_phone' => '+14155550123',
    'opt_in_type' => 'WEB_FORM',
    'opt_in_image_urls' => [
        'https://acme.example.com/opt-in-proof.png'
    ],
    'message_volume' => '10,000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit"

	payload := strings.NewReader("{\n  \"use_case\": \"Customer Care\",\n  \"use_case_summary\": \"Appointment reminders and order-status updates for customers who opted in at checkout.\",\n  \"sample_messages\": [\n    \"Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.\"\n  ],\n  \"business_name\": \"Acme Co\",\n  \"business_website\": \"https://acme.example.com\",\n  \"ein\": \"12-3456789\",\n  \"contact_email\": \"compliance@acme.example.com\",\n  \"contact_phone\": \"+14155550123\",\n  \"opt_in_type\": \"WEB_FORM\",\n  \"opt_in_image_urls\": [\n    \"https://acme.example.com/opt-in-proof.png\"\n  ],\n  \"message_volume\": \"10,000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"use_case\": \"Customer Care\",\n  \"use_case_summary\": \"Appointment reminders and order-status updates for customers who opted in at checkout.\",\n  \"sample_messages\": [\n    \"Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.\"\n  ],\n  \"business_name\": \"Acme Co\",\n  \"business_website\": \"https://acme.example.com\",\n  \"ein\": \"12-3456789\",\n  \"contact_email\": \"compliance@acme.example.com\",\n  \"contact_phone\": \"+14155550123\",\n  \"opt_in_type\": \"WEB_FORM\",\n  \"opt_in_image_urls\": [\n    \"https://acme.example.com/opt-in-proof.png\"\n  ],\n  \"message_volume\": \"10,000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"use_case\": \"Customer Care\",\n  \"use_case_summary\": \"Appointment reminders and order-status updates for customers who opted in at checkout.\",\n  \"sample_messages\": [\n    \"Your order #1234 has shipped and arrives Tuesday. Reply STOP to opt out.\"\n  ],\n  \"business_name\": \"Acme Co\",\n  \"business_website\": \"https://acme.example.com\",\n  \"ein\": \"12-3456789\",\n  \"contact_email\": \"compliance@acme.example.com\",\n  \"contact_phone\": \"+14155550123\",\n  \"opt_in_type\": \"WEB_FORM\",\n  \"opt_in_image_urls\": [\n    \"https://acme.example.com/opt-in-proof.png\"\n  ],\n  \"message_volume\": \"10,000\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "phoneNumberId": "<string>",
    "phoneNumber": "<string>",
    "tfvStatus": "not_submitted",
    "tfvProvider": "<string>",
    "tfvProviderSubmissionId": "<string>",
    "tfvSubmittedAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docs_url": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Dashboard JWT token from Clerk

Path Parameters

string

required

Body

application/json

use_case

string

required

Toll-free messaging use case (from the carrier-approved use-case list, e.g. Customer Care).

use_case_summary

string

required

40–500 character description of how the number is used.

Required string length: 40 - 500

sample_messages

string[]

required

1–5 representative outbound messages the carrier will review.

Required array length: 1 - 5 elements

business_name

string

required

business_website

string<uri>

required

contact_email

string<email>

required

contact_phone

string

required

E.164 contact phone (e.g. +14155550123).

opt_in_type

enum<string>

required

How subscribers opted in to messaging.

Available options:

VERBAL,

WEB_FORM,

PAPER_FORM,

VIA_TEXT,

MOBILE_QR_CODE

opt_in_image_urls

string<uri>[]

required

1–5 HTTPS URLs to opt-in proof screenshots.

Required array length: 1 - 5 elements

message_volume

string

required

Expected monthly message-volume band (e.g. "10,000").

ein

string

US Employer Identification Number (xx-xxxxxxx). Supply this OR business_registration_number + business_registration_country.

business_registration_number

string

business_registration_country

string

ISO-3166 alpha-2 country of the business registration number.

additional_information

string

is_political

boolean

Set true for political messaging; requires cv_token.

cv_token

string

Campaign Verify authorization token (required for political use cases).

Response

The toll-free verification status after the submission

data

object

Show child attributes

API Reference

All Endpoints

Submit or resubmit a toll-free number for verification (TFV)

Authorizations

Path Parameters

Body

Response