Update Verification Request

Update an existing tollfree verification request. This is particularly useful when there are pending customer actions to be taken.

PATCH /messaging_tollfree/verification/requests/{id}

JavaScript

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const verificationRequestEgress = await client.messagingTollfree.verification.requests.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  {
    additionalInformation: 'additionalInformation',
    businessAddr1: '600 Congress Avenue',
    businessCity: 'Austin',
    businessContactEmail: '[e-mail]',
    businessContactFirstName: 'John',
    businessContactLastName: 'Doe',
    businessContactPhone: '[phone]',
    businessName: 'Telnyx LLC',
    businessState: 'Texas',
    businessZip: '78701',
    corporateWebsite: 'http://example.com',
    messageVolume: '100,000',
    optInWorkflow:
      "User signs into the Telnyx portal, enters a number and is prompted to select whether they want to use 2FA verification for security purposes. If they've opted in a confirmation message is sent out to the handset",
    optInWorkflowImageURLs: [
      { url: 'https://telnyx.com/sign-up' },
      { url: 'https://telnyx.com/company/data-privacy' },
    ],
    phoneNumbers: [{ phoneNumber: '[phone]' }, { phoneNumber: '[phone]' }],
    productionMessageContent: 'Your Telnyx OTP is XXXX',
    useCase: '2FA',
    useCaseSummary:
      'This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal',
  },
);

console.log(verificationRequestEgress.id);

200

{
  "businessName": "Telnyx LLC",
  "corporateWebsite": "http://example.com",
  "businessAddr1": "600 Congress Avenue",
  "businessCity": "Austin",
  "businessState": "Texas",
  "businessZip": "78701",
  "businessContactFirstName": "John",
  "businessContactLastName": "Doe",
  "businessContactEmail": "[e-mail]",
  "businessContactPhone": "[phone]",
  "messageVolume": "100,000",
  "phoneNumbers": [
    {
      "phoneNumber": "[phone]"
    },
    {
      "phoneNumber": "[phone]"
    }
  ],
  "useCase": "2FA",
  "useCaseSummary": "This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal",
  "productionMessageContent": "Your Telnyx OTP is XXXX",
  "optInWorkflow": "User signs into the Telnyx portal, enters number and is prompted to select whether they want to use 2FA verification for security purposes. If they've opted in a confirmation message is sent out to the handset",
  "optInWorkflowImageURLs": [
    {
      "url": "https://telnyx.com/sign-up"
    },
    {
      "url": "https://telnyx.com/company/data-privacy"
    }
  ],
  "additionalInformation": "This is for security purposes, blah blah blah",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "verificationRequestId": "<string>",
  "businessAddr2": "14th Floor",
  "isvReseller": "Yes",
  "webhookUrl": "http://example-webhook.com",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessRegistrationCountry": "US",
  "doingBusinessAs": "Acme Services",
  "entityType": "PRIVATE_PROFIT",
  "optInConfirmationResponse": "You have successfully opted in to receive messages from Acme Corp",
  "helpMessageResponse": "Reply HELP for assistance or STOP to unsubscribe. Contact: [e-mail]",
  "privacyPolicyURL": "https://example.com/privacy",
  "termsAndConditionURL": "https://example.com/terms",
  "ageGatedContent": false,
  "optInKeywords": "START, YES, SUBSCRIBE",
  "campaignVerifyAuthorizationToken": "cv_token_abc123xyz",
  "verificationStatus": "In Progress"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id · string<uuid> · required

Unique identifier of the resource.

Body

application/json

The body of a tollfree verification request

businessName · string · required

Name of the business; there are no specific formatting requirements

Maximum string length: 500

Example:

"Telnyx LLC"

corporateWebsite · string · required

A URL, including the scheme, pointing to the corporate website

Maximum string length: 500

Example:

"http://example.com"

businessAddr1 · string · required

Line 1 of the business address

Maximum string length: 500

Example:

"600 Congress Avenue"

businessCity · string · required

The city of the business address; the first letter should be capitalized

Maximum string length: 500

Example:

"Austin"

businessState · string · required

The full name of the state (not the 2 letter code) of the business address; the first letter should be capitalized

Maximum string length: 500

Example:

"Texas"

businessZip · string · required

The ZIP code of the business address

Maximum string length: 500

Example:

"78701"

businessContactFirstName · string · required

First name of the business contact; there are no specific requirements on formatting

Maximum string length: 500

Example:

"John"

businessContactLastName · string · required

Last name of the business contact; there are no specific requirements on formatting

Maximum string length: 500

Example:

"Doe"

businessContactEmail · string · required

The email address of the business contact

Maximum string length: 500

Example:

"[e-mail]"

businessContactPhone · string · required

The phone number of the business contact in E.164 format

Maximum string length: 500

Example:

"[phone]"

messageVolume · enum<string> · required

Estimated monthly volume of messages from the given phone numbers

Available options: 10, 100, 1,000, 10,000, 100,000, 250,000, 500,000, 750,000, 1,000,000, 5,000,000, 10,000,000+

Example:

"100,000"

phoneNumbers · PhoneNumber · object[] · required

The phone numbers to request the verification of

Minimum array length: 1

Show child attributes

Example:

[
  { "phoneNumber": "[phone]" },
  { "phoneNumber": "[phone]" }
]

useCase · enum<string> · required

Machine-readable use-case for the phone numbers

Available options: 2FA, App Notifications, Appointments, Auctions, Auto Repair Services, Bank Transfers, Billing, Booking Confirmations, Business Updates, COVID-19 Alerts, Career Training, Chatbot, Conversational / Alerts, Courier Services & Deliveries, Emergency Alerts, Events & Planning, Financial Services, Fraud Alerts, Fundraising, General Marketing, General School Updates, HR / Staffing, Healthcare Alerts, Housing Community Updates, Insurance Services, Job Dispatch, Legal Services, Mixed, Motivational Reminders, Notary Notifications, Order Notifications, Political, Public Works, Real Estate Services, Religious Services, Repair and Diagnostics Alerts, Rewards Program, Surveys, System Alerts, Voting Reminders, Waitlist Alerts, Webinar Reminders, Workshop Alerts

Example:

"2FA"

useCaseSummary · string · required

Human-readable summary of the desired use-case

Maximum string length: 500

Example:

"This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal"

productionMessageContent · string · required

An example of a message that will be sent from the given phone numbers

Maximum string length: 1000

Example:

"Your Telnyx OTP is XXXX"

optInWorkflow · string · required

Human-readable description of how end users will opt into receiving messages from the given phone numbers

Maximum string length: 500

Example:

"User signs into the Telnyx portal, enters a number and is prompted to select whether they want to use 2FA verification for security purposes. If they've opted in a confirmation message is sent out to the handset"

optInWorkflowImageURLs · Url · object[] · required

Images showing the opt-in workflow

Minimum array length: 1

Show child attributes

Example:

[
  { "url": "https://telnyx.com/sign-up" },
  {
    "url": "https://telnyx.com/company/data-privacy"
  }
]

additionalInformation · string · required

Any additional information

Maximum string length: 500

businessAddr2 · string

Line 2 of the business address

Maximum string length: 500

Example:

"14th Floor"

isvReseller · string | null

ISV name

Maximum string length: 500

webhookUrl · string

URL that should receive webhooks relating to this verification request

Maximum string length: 500

Example:

"http://example-webhook.com"

businessRegistrationNumber · string | null

Official business registration number (e.g., Employer Identification Number (EIN) in the U.S.). Required from January 2026.

Maximum string length: 500

Example:

"12-3456789"

businessRegistrationType · string | null

Type of business registration being provided. Required from January 2026.

Maximum string length: 500

Example:

"EIN"

businessRegistrationCountry · string | null

ISO 3166-1 alpha-2 country code of the issuing business authority. Must be exactly 2 letters. Automatically converted to uppercase. Required from January 2026.

Maximum string length: 2

Pattern: ^[A-Z]{2}$

Example:

"US"

doingBusinessAs · string | null

Doing Business As (DBA) name if different from legal name

Maximum string length: 500

Example:

"Acme Services"

entityType · enum<string> | null

Business entity classification. Must be one of the 5 valid enum values.

Available options: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT

optInConfirmationResponse · string | null

Message sent to users confirming their opt-in to receive messages

Maximum string length: 500

Example:

"You have successfully opted in to receive messages from Acme Corp"

helpMessageResponse · string | null

The message returned when users text 'HELP'

Maximum string length: 500

Example:

"Reply HELP for assistance or STOP to unsubscribe. Contact: [e-mail]"

privacyPolicyURL · string | null

URL pointing to the business's privacy policy. Plain string, no URL format validation.

Maximum string length: 500

Example:

"https://example.com/privacy"

termsAndConditionURL · string | null

URL pointing to the business's terms and conditions. Plain string, no URL format validation.

Maximum string length: 500

Example:

"https://example.com/terms"

ageGatedContent · boolean · default: false

Indicates if messaging content requires age gating (e.g., 18+). Defaults to false if not provided.

optInKeywords · string | null

Keywords used to collect and process consumer opt-ins

Maximum string length: 500

Example:

"START, YES, SUBSCRIBE"

campaignVerifyAuthorizationToken · string | null

Campaign Verify Authorization Token required for Political use case submissions starting February 17, 2026. This token is validated by Zipwhip and must be provided for all Political use case verifications after the deadline.

Maximum string length: 500

Example:

"cv_token_abc123xyz"

Response

200

application/json

Successful Response

A verification request as it comes out of the database

businessName · string · required

Example:

"Telnyx LLC"

corporateWebsite · string · required

Example:

"http://example.com"

businessAddr1 · string · required

Example:

"600 Congress Avenue"

businessCity · string · required

Example:

"Austin"

businessState · string · required

Example:

"Texas"

businessZip · string · required

Example:

"78701"

businessContactFirstName · string · required

Example:

"John"

businessContactLastName · string · required

Example:

"Doe"

businessContactEmail · string · required

Example:

"[e-mail]"

businessContactPhone · string · required

Example:

"[phone]"

messageVolume · enum<string> · required

One of the following exact values: 10; 100; 1,000; 10,000; 100,000; 250,000; 500,000; 750,000; 1,000,000; 5,000,000; 10,000,000+

Available options: 10, 100, 1,000, 10,000, 100,000, 250,000, 500,000, 750,000, 1,000,000, 5,000,000, 10,000,000+

Example:

"100,000"

phoneNumbers · PhoneNumber · object[] · required

Show child attributes

Example:

[
  { "phoneNumber": "[phone]" },
  { "phoneNumber": "[phone]" }
]

useCase · enum<string> · required

Tollfree usecase categories

Available options: 2FA, App Notifications, Appointments, Auctions, Auto Repair Services, Bank Transfers, Billing, Booking Confirmations, Business Updates, COVID-19 Alerts, Career Training, Chatbot, Conversational / Alerts, Courier Services & Deliveries, Emergency Alerts, Events & Planning, Financial Services, Fraud Alerts, Fundraising, General Marketing, General School Updates, HR / Staffing, Healthcare Alerts, Housing Community Updates, Insurance Services, Job Dispatch, Legal Services, Mixed, Motivational Reminders, Notary Notifications, Order Notifications, Political, Public Works, Real Estate Services, Religious Services, Repair and Diagnostics Alerts, Rewards Program, Surveys, System Alerts, Voting Reminders, Waitlist Alerts, Webinar Reminders, Workshop Alerts

Example:

"2FA"

useCaseSummary · string · required

Example:

"This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal"

productionMessageContent · string · required

Example:

"Your Telnyx OTP is XXXX"

optInWorkflow · string · required

Example:

"User signs into the Telnyx portal, enters number and is prompted to select whether they want to use 2FA verification for security purposes. If they've opted in a confirmation message is sent out to the handset"

optInWorkflowImageURLs · Url · object[] · required

Show child attributes

Example:

[
  { "url": "https://telnyx.com/sign-up" },
  {
    "url": "https://telnyx.com/company/data-privacy"
  }
]

additionalInformation · string · required

Example:

"This is for security purposes, blah blah blah"

id · string<uuid> · required

verificationRequestId · string · required

businessAddr2 · string

Example:

"14th Floor"

isvReseller · string

Example:

"Yes"

webhookUrl · string

Example:

"http://example-webhook.com"

businessRegistrationNumber · string

Example:

"12-3456789"

businessRegistrationType · string

Example:

"EIN"

businessRegistrationCountry · string

Example:

"US"

doingBusinessAs · string

Example:

"Acme Services"

entityType · enum<string>

Business entity classification

Available options: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT

Example:

"PRIVATE_PROFIT"

optInConfirmationResponse · string

Example:

"You have successfully opted in to receive messages from Acme Corp"

helpMessageResponse · string

Example:

"Reply HELP for assistance or STOP to unsubscribe. Contact: [e-mail]"

privacyPolicyURL · string

Example:

"https://example.com/privacy"

termsAndConditionURL · string

Example:

"https://example.com/terms"

ageGatedContent · boolean

Example:

false

optInKeywords · string

Example:

"START, YES, SUBSCRIBE"

campaignVerifyAuthorizationToken · string | null

Campaign Verify Authorization Token required for Political use case submissions starting February 17, 2026

Maximum string length: 500

Example:

"cv_token_abc123xyz"

verificationStatus · enum<string> · default: In Progress

Tollfree verification status

Available options: Verified, Rejected, Waiting For Vendor, Waiting For Customer, Waiting For Telnyx, In Progress