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

businessNamestring required

Name of the business; there are no specific formatting requirements

corporateWebsitestring required

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

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

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

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

businessContactEmailstring required

The email address of the business contact

businessContactPhonestring required

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

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

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

productionMessageContentstring required

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

optInWorkflowstring required

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

additionalInformationstring required

Any additional information

isvResellerstring nullable

ISV name

webhookUrlstring

URL that should receive webhooks relating to this verification request

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.

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.

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

optInConfirmationResponsestring nullable

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

helpMessageResponsestring nullable

The message returned when users text 'HELP'

privacyPolicyURLstring nullable

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

termsAndConditionURLstring nullable

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

ageGatedContentboolean

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

optInKeywordsstring nullable

Keywords used to collect and process consumer opt-ins

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.

Example request

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

Response

Successful Response

businessNamestring required
corporateWebsitestring required
businessAddr1string required
businessAddr2string
businessCitystring required
businessStatestring required
businessZipstring required
businessContactFirstNamestring required
businessContactLastNamestring required
businessContactEmailstring required
businessContactPhonestring required
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

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
productionMessageContentstring required
optInWorkflowstring required
additionalInformationstring required
isvResellerstring
webhookUrlstring
businessRegistrationNumberstring
businessRegistrationTypestring
businessRegistrationCountrystring
doingBusinessAsstring
entityType'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT'

Business entity classification

optInConfirmationResponsestring
helpMessageResponsestring
privacyPolicyURLstring
termsAndConditionURLstring
ageGatedContentboolean
optInKeywordsstring
campaignVerifyAuthorizationTokenstring nullable

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

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

Tollfree verification status

Example response

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

Changes

Changed in 3 of the 99 revisions of this API.69

  • a6a61a29ecdd23See the full diff
    • ▲

      removed from the request property anyOf list

      request-property-any-of-removed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ○

      added to the request property anyOf list

      request-property-any-of-added

    • ○

      added to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      removed from the response property allOf list for the response status

      response-property-all-of-removed

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

  • 1571b0380bd723See the full diff
    • ▲

      removed from the request property anyOf list

      request-property-any-of-removed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    • ○

      added to the request property anyOf list

      request-property-any-of-added

    • ○

      added to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      removed from the response property allOf list for the response status

      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 from the request property anyOf list

      request-property-any-of-removed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ○

      added to the request property anyOf list

      request-property-any-of-added

    • ○

      added to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      removed from the response property allOf list for the response status

      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

Of the 99 revisions, 1 has no diff computed.