How to Register a Toll-Free Number (TFN) via the API

Objective

Register a Toll-Free Number (TFN) for SMS and MMS messaging in the US and Canada using the Vonage TFN Registration API.

Applies To

• TFN Registration API

• Vonage SMS API

• Vonage MMS API

• US and Canada Toll-Free Numbers (TFNs)

Procedure

Before you begin, read the Toll-Free Number Messaging Registration — US & Canada guide.

Note: TFN registration does not guarantee messaging service activation or deliverability. New requests are vetted for accurate program information, and traffic is subject to content filtering by carriers.

Step 1 — Create a TFN Registration

Send a POST request with your business profile and messaging campaign details.

Endpoint:

POST https://api.nexmo.com/v1/tfn/registrations

Example request — Standard registration:

{
  "account_id": "abcd1234",
  "organization_name": "Acme Corp",
  "organization_address": {
    "street": "23 Main Street",
    "city": "Holmdel",
    "state": "NJ",
    "postal_code": "07733",
    "country": "US"
  },
  "organization_website": "https://acmecorp.com",
  "organization_contact": {
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "15556660001",
    "email": "jane@example.com"
  },
  "entity_type": "PRIVATE_PROFIT",
  "tax_identifier_type": "EIN",
  "tax_identifier_number": "20-1111111",
  "tax_identifier_issuing_country": "US",
  "toll_free_numbers": ["18005550001"],
  "estimated_monthly_volume": "10000",
  "use_case_category": "CUSTOMER_CARE",
  "use_case_description": "Acme Corp collects mobile numbers at checkout to send order status notifications to customers.",
  "message_content": "AcmeCorp: Your order #12345 has shipped! Track it here: https://acmecorp.com/track. Reply STOP to cancel.",
  "opt_in_workflow": "ONLINE",
  "opt_in_consent_link": "https://acmecorp.com/sms-opt-in",
  "subscriber_opt_out": true,
  "opt_out_keywords": "STOP",
  "subscriber_help": true,
  "help_keywords": "HELP",
  "help_message": "AcmeCorp: For support, visit https://acmecorp.com/support or call 1-800-555-0001.",
  "age_gated": false
}

All attributes are required unless specified otherwise. For a full list of required and optional parameters, refer to the TFN Registration API Reference.

Notes on key fields:

Compliance requirement (effective February 17, 2026): The fields entity_type, tax_identifier_type, tax_identifier_number, and tax_identifier_issuing_country are mandatory for all new TFN registrations.

Political use cases: If your use_case_category is POLITICAL, a valid Campaign Verify (CV) token is required. Generate your token at campaignverify.org before submitting, and include it as campaign_verify_token in your request.

Successful response (HTTP 201):

{
  "registration_id": "fed44020-ac68-45d2-a931-0e6e309a29c7",
  "account_id": "abcd1234",
  "toll_free_numbers": ["18005550001"],
  "status": "PENDING_REVIEW",
  "created_date": "2026-04-22T10:00:00.000Z",
  "last_updated": "2026-04-22T10:00:00.000Z"
}

Note: Save the registration_id from the response — you will need it to retrieve registration details and track status updates.

Step 2 — Check Your Registration Status

Once submitted, use the Retrieve TFN Registration Details endpoint to check the current status of your registration.

Endpoint:

GET https://api.nexmo.com/v1/tfn/registrations/{registration_id}

Example:

GET https://api.nexmo.com/v1/tfn/registrations/fed44020-ac68-45d2-a931-0e6e309a29c7

Registration statuses:

Timeline: The registration process typically takes 2–10 business days to complete.

You can also retrieve the full event history of a registration using:

GET https://api.nexmo.com/v1/tfn/registrations/{registration_id}/events

Step 3 — Update a Registration (if required)

If your registration moves to UPDATES_REQUIRED status, you will receive an email with instructions on what needs to be corrected. Use the PUT endpoint to update and resubmit your registration.

Endpoint:

PUT https://api.nexmo.com/v1/tfn/registrations/{registration_id}

Example — Updating the opt-in consent link:

{
  "opt_in_consent_link": "https://acmecorp.com/updated-sms-opt-in",
  "use_case_description": "Acme Corp collects mobile numbers at checkout to send order status and delivery notifications to customers who have opted in via our website."
}

Note: Once a registration has been submitted, the toll_free_numbers field and the reseller_contact_email field cannot be updated. If you need to change the TFN associated with a registration, use the Re-register feature instead.

Successful response (HTTP 200):

{
  "registration_id": "fed44020-ac68-45d2-a931-0e6e309a29c7",
  "status": "PENDING_REVIEW",
  "last_updated": "2026-04-22T14:00:00.000Z"
}

What Happens Next?

If your registration is approved (REGISTERED):

• You will receive an email confirmation.

• Your TFN can now send SMS and MMS messages in the US and Canada.

• No further action is required.

If your registration requires updates (UPDATES_REQUIRED):

• You will receive an email with specific instructions.

• Update the relevant fields using the PUT endpoint (Step 3 above).

• Resubmit — the status will return to PENDING_REVIEW.

If your registration is rejected (REJECTED) or blocked (BLOCKED):

• You will receive an email with the reason.

• Rejected and blocked registrations cannot be resubmitted.

• For blocked TFNs, it is advisable to release the number from your account, as repurposing it may result in the same outcome.

• If you believe the decision was made in error, submit a Support request.

Additional Information

Authentication

The TFN Registration API supports both JWT and Basic Auth:

Related Articles:

• Toll-Free Number Messaging Registration — US & Canada

• Vonage Self-Serve TFN Registration Guide (Dashboard)

• TFN Registration API Reference

• TFN Registration Developer Documentation