Sign in
Verification Requests

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}

Path parameters

idstring uuid required

Unique identifier of the resource.

Request body

additionalInformationstring required

Any additional information

ageGatedContentboolean

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

businessAddr1string required

Line 1 of the business address

businessAddr2string

Line 2 of the business address

businessCitystring required

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

businessContactEmailstring required

The email address of the business contact

businessContactFirstNamestring required

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

businessContactLastNamestring required

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

businessContactPhonestring required

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

businessNamestring required

Name of the business; there are no specific formatting requirements

businessRegistrationCountrystring nullable

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.

businessRegistrationNumberstring nullable

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

businessRegistrationTypestring nullable

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

businessStatestring required

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

businessZipstring required

The ZIP code of the business address

campaignVerifyAuthorizationTokenstring nullable

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.

corporateWebsitestring required

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

doingBusinessAsstring nullable

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

entityType'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT'

Business entity classification

helpMessageResponsestring nullable

The message returned when users text 'HELP'

isvResellerstring nullable

ISV name

messageVolume'10' | '100' | '1,000' | '10,000' | '100,000' | '250,000' | '500,000' | '750,000' | '1,000,000' | '5,000,000' | '10,000,000+' required

Message Volume Enums

optInConfirmationResponsestring nullable

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

optInKeywordsstring nullable

Keywords used to collect and process consumer opt-ins

optInWorkflowstring required

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

privacyPolicyURLstring nullable

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

productionMessageContentstring required

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

termsAndConditionURLstring nullable

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

useCase'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' required

Tollfree usecase categories

useCaseSummarystring required

Human-readable summary of the desired use-case

webhookUrlstring

URL that should receive webhooks relating to this verification request

Example request

{
  "businessAddr1": "600 Congress Avenue",
  "businessAddr2": "14th Floor",
  "businessCity": "Austin",
  "businessContactEmail": "email@example.com",
  "businessContactFirstName": "John",
  "businessContactLastName": "Doe",
  "businessContactPhone": "+18005550100",
  "businessName": "Telnyx LLC",
  "businessRegistrationCountry": "US",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessState": "Texas",
  "businessZip": "78701",
  "campaignVerifyAuthorizationToken": "cv_token_abc123xyz",
  "corporateWebsite": "http://example.com",
  "doingBusinessAs": "Acme Services",
  "helpMessageResponse": "Reply HELP for assistance or STOP to unsubscribe. Contact: support@example.com",
  "optInConfirmationResponse": "You have successfully opted in to receive messages from Acme Corp",
  "optInKeywords": "START, YES, SUBSCRIBE",
  "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": "+18773554398"
    },
    {
      "phoneNumber": "+18773554399"
    }
  ],
  "privacyPolicyURL": "https://example.com/privacy",
  "productionMessageContent": "Your Telnyx OTP is XXXX",
  "termsAndConditionURL": "https://example.com/terms",
  "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",
  "webhookUrl": "http://example-webhook.com"
}

Response

Successful Response

additionalInformationstring required
ageGatedContentboolean
businessAddr1string required
businessAddr2string
businessCitystring required
businessContactEmailstring required
businessContactFirstNamestring required
businessContactLastNamestring required
businessContactPhonestring required
businessNamestring required
businessRegistrationCountrystring
businessRegistrationNumberstring
businessRegistrationTypestring
businessStatestring required
businessZipstring required
campaignVerifyAuthorizationTokenstring nullable

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

corporateWebsitestring required
doingBusinessAsstring
entityType'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT'

Business entity classification

helpMessageResponsestring
idstring uuid required
isvResellerstring
messageVolume'10' | '100' | '1,000' | '10,000' | '100,000' | '250,000' | '500,000' | '750,000' | '1,000,000' | '5,000,000' | '10,000,000+' required

Message Volume Enums

optInConfirmationResponsestring
optInKeywordsstring
optInWorkflowstring required
privacyPolicyURLstring
productionMessageContentstring required
termsAndConditionURLstring
useCase'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' required

Tollfree usecase categories

useCaseSummarystring required
verificationRequestIdstring required
verificationStatus'Verified' | 'Rejected' | 'Waiting For Vendor' | 'Waiting For Customer' | 'Waiting For Telnyx' | 'In Progress'

Tollfree verification status

webhookUrlstring

Example response

{
  "additionalInformation": "This is for security purposes, blah blah blah",
  "businessAddr1": "600 Congress Avenue",
  "businessAddr2": "14th Floor",
  "businessCity": "Austin",
  "businessContactEmail": "email@example.com",
  "businessContactFirstName": "John",
  "businessContactLastName": "Doe",
  "businessContactPhone": "+18005550100",
  "businessName": "Telnyx LLC",
  "businessRegistrationCountry": "US",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessState": "Texas",
  "businessZip": "78701",
  "campaignVerifyAuthorizationToken": "cv_token_abc123xyz",
  "corporateWebsite": "http://example.com",
  "doingBusinessAs": "Acme Services",
  "helpMessageResponse": "Reply HELP for assistance or STOP to unsubscribe. Contact: support@example.com",
  "isvReseller": "Yes",
  "optInConfirmationResponse": "You have successfully opted in to receive messages from Acme Corp",
  "optInKeywords": "START, YES, SUBSCRIBE",
  "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"
    }
  ],
  "phoneNumbers": [
    {
      "phoneNumber": "+18773554398"
    },
    {
      "phoneNumber": "+18773554399"
    }
  ],
  "privacyPolicyURL": "https://example.com/privacy",
  "productionMessageContent": "Your Telnyx OTP is XXXX",
  "termsAndConditionURL": "https://example.com/terms",
  "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",
  "webhookUrl": "http://example-webhook.com"
}

Changes

Changed in 2 of the 61 revisions of this API.46

  • 1571b0380bd723See the full diff
    • ▲

      removed messaging_toll_free_verification_EntityType from the entityType request property anyOf list

      request-property-any-of-removed

    • ▲

      the errors/items/code response's property type/format changed from integer/int32 to string/ for status 4XX

      response-property-type-changed

    • ○

      added toll-free-verification_EntityType to the entityType request property anyOf list

      request-property-any-of-added

    • ○

      added toll-free-verification_EntityType to the entityType response property allOf list for the response status 200

      response-property-all-of-added

    • ○

      removed messaging_toll_free_verification_EntityType from the entityType response property allOf list for the response status 200

      response-property-all-of-removed

    This revision also has 64 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 8f5f4e53799423See the full diff
    • ▲

      removed toll-free-verification_EntityType from the entityType request property anyOf list

      request-property-any-of-removed

    • ▲

      the errors/items/code response's property type/format changed from string/ to integer/int32 for status 4XX

      response-property-type-changed

    • ○

      added messaging_toll_free_verification_EntityType to the entityType request property anyOf list

      request-property-any-of-added

    • ○

      added messaging_toll_free_verification_EntityType to the entityType response property allOf list for the response status 200

      response-property-all-of-added

    • ○

      removed toll-free-verification_EntityType from the entityType response property allOf list for the response status 200

      response-property-all-of-removed

    This revision also has 41 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog