PreCheck - Toll-Free Number

Rapid checks for Toll-Free Number (TFN) Brand and Message Campaign Compliance

Introduction and Use Cases

Use the TFN PreCheck API to run KYB and compliance analyses on brand and Toll-Free Number (TFN) messaging campaign information. The API returns results within minutes so you can find compliance issues before formal review. Treat PreCheck results as guidance, not a guarantee of approval or rejection, because carriers, aggregators, and verification authorities each run their own review processes.

Different entities can use these APIs at different points in the Campaign Launch lifecycle:

  • CSPs / Texting Platforms

    • Catch potential launch issues before submitting to aggregators for onboarding

    • Reduce time to launch and internal review overhead

  • Aggregators

    • Run pre-flight checks before submitting to DCAs (if applicable), verification authorities, and carriers

    • Automate carrier-expected campaign compliance checks


API Workflow

At a high level, the workflow for a single PreCheck looks like this:

1. Client Sends a PreCheck Request

  • POST with JSON body containing brand, agent, and messaging details
  • Specify which analysisSteps to run
  • Include a callbackUrl where results should be delivered.

Real Request Payload Example

This payload exercises every optional, conditional, and mandatory field across all verification steps (including age-gated, vertical rules, and sample object structures).

{
  "externalProjectId": "internal-crm-id-9981x",
  "callbackUrl": "[https://api.yourplatform.com/v1/webhooks/texter-precheck](https://api.yourplatform.com/v1/webhooks/texter-precheck)",
  "analysisSteps": [
    "brand_background_check",
    "brand_online_presence_check",
    "poc_email_domain_check",
    "privacy_policy_check",
    "terms_of_service_check",
    "opt_in_method_check",
    "opt_in_message_check",
    "opt_out_message_check",
    "help_message_check",
    "campaign_description_check",
    "sample_messages_check",
    "use_case_consistency_check",
    "shaft_content_check",
    "prohibited_use_case_check"
  ],
  "legalName": "Acme Global Solutions LLC",
  "dbaName": "Acme Text Support",
  "businessIdentifier": "12-3456789",
  "registeredBusinessAddress": "123 Market Street, Suite 400, Austin, TX 78701",
  "businessWebsiteUrl": "[https://www.acme-example-global.com](https://www.acme-example-global.com)",
  "brandPocEmail": "[email protected]",
  "brandVerticalType": "FINANCIAL",
  "privacyPolicyUrl": "[https://www.acme-example-global.com/privacy](https://www.acme-example-global.com/privacy)",
  "termsOfServiceUrl": "[https://www.acme-example-global.com/terms](https://www.acme-example-global.com/terms)",
  "ageGated": true,
  "optInMethods": [
    "WEB_FORM",
    "SMS_KEYWORD"
  ],
  "optInMethodURLs": [
    "[https://www.acme-example-global.com/sms-signup](https://www.acme-example-global.com/sms-signup)"
  ],
  "optInDescription": "Subscribers text START to our number or check an explicit box labeled 'I consent to receive text alerts' on our web form.",
  "optInKeywords": [
    "START",
    "JOIN"
  ],
  "optInMessage": "Acme Alerts: Welcome! Reply YES to confirm subscription. Msg&Data rates may apply. Freq varies. Reply STOP to cancel, HELP for help.",
  "optOutKeywords": [
    "STOP",
    "END"
  ],
  "optOutMessage": "Acme Alerts: You have successfully been unsubscribed. You will receive no further messages from this service.",
  "helpKeywords": [
    "HELP"
  ],
  "helpMessage": "Acme Alerts: For support, call 1-800-555-0199 or visit [https://www.acme-example-global.com/support](https://www.acme-example-global.com/support). Msg&Data rates may apply.",
  "campaignDescription": "This campaign delivers multi-factor authentication (MFA) pins, account alerts, and balance change notices to registered retail accounts.",
  "useCase": "FINANCIAL_SERVICES",
  "subUseCases": [
    "2FA",
    "ACCOUNT_NOTIFICATION"
  ],
  "directLending": false,
  "affiliateMarketing": false,
  "embeddedLink": "[https://acme-example-global.com/verify-login](https://acme-example-global.com/verify-login)",
  "embeddedPhone": "+18005550199",
  "sampleMessages": [
    {
      "content": "Acme Alerts: Your verification code is [123456]. This expires in 5 minutes. Reply STOP to opt out.",
      "useCase": "2FA"
    },
    {
      "content": "Acme Alerts: A login was detected on your account from a new device. Verify at [https://acme-example-global.com/verify-login](https://acme-example-global.com/verify-login). Reply HELP for assistance.",
      "useCase": "ACCOUNT_NOTIFICATION"
    }
  ]
}

2. Synchronous Validation

The API validates the payload structure immediately.

  • On Success (200 OK): The payload passed initial schema checks and the asynchronous analysis has been queued.

  • On Failure (4xx): The synchronous validation failed. Review the returned details to fix your payload parameters.

    Real 200 OK Success Response Payload

    On success, the API returns:

    • projectId (TexterID project ID. Each PreCheck API call creates a new projectId.)

    • projectUrl (TexterID dashboard link. Open this page to view analysis results in real time.)

    • analysisId (Specific ID for the analysis run.)

    {
      "projectId": "proj_texter_98765",
      "projectUrl": "[https://dashboard.texterid.com/projects/proj_texter_98765](https://dashboard.texterid.com/projects/proj_texter_98765)",
      "analysisId": "analysis_abc123xyz"
    }

Real 400 Bad Request Response Payload

If synchronous validation fails, the API returns a 4xx with issue details.

{
  "errorCode": "VALIDATION_FAILED",
  "errorMessage": "Synchronous validation failed. Missing required fields for an analysis step.",
  "details": [
    {
      "issue": "Missing required field 'businessIdentifier' for analysis step 'brand_background_check'."
    }
  ]
}

❗️

Potential validation issues include:

  • Invalid analysis steps provided or missing prerequisites

  • Missing required fields for an analysis step.

3. Asynchronous Analysis

  • The API runs the requested analysisSteps in parallel (after any necessary prerequisite steps complete).

  • Once finished, the API posts a JSON webhook payload with the final analysis results to your designated callbackUrl.


Testing Callbacks

To test the results callback, you can use a service like Webhook.sitehttps://webhook.site

🔒

Security Requirement The callbackUrl must use a secure HTTPS protocol.


Analysis Steps

The analysisSteps array lets you choose which checks to run for a given PreCheck request.

Each step ID below can be included in the analysisSteps array:


Step ID

Description

Required Fields

Optional Fields

Depends on Steps

brand_background_check

Verifies the submitted EIN and business information align with public records. POC Name and Address may be included in the check.

legalName, businessIdentifier, registeredBusinessAddress (must be US)

``

brand_online_presence_check

Crawls the submitted website to produce a structured summary of the organization's commercial activities for use by downstream checks. Verifies that the site resolves publicly and plausibly belongs to the submitting organization.

businessWebsiteUrl, legalName

poc_email_domain_check

Verifies that the POC email address uses a domain consistent with the submitting organization's website.

brandPocEmail, legalName, businessWebsiteUrl

brand_online_presence_check

privacy_policy_check

Verifies that the privacy policy URL is accessible, belongs to the submitting organization, and contains substantive privacy content. Specifically checks for an explicit clause that SMS opt-in data and consent will not be shared with third parties. Generic data collection language without this SMS-specific clause fails. If the URL is valid but content cannot be retrieved, the step returns SKIPPED with justification.

privacyPolicyUrl, legalName, businessWebsiteUrl

brand_online_presence_check

terms_of_service_check

Verifies that the TOS URL is accessible and contains substantive terms belonging to the submitting organization. Checks for the five required SMS elements: brand or program name, 'message and data rates may apply', message frequency disclosure, STOP opt-out instructions, and HELP or support contact. If the URL is valid but content cannot be retrieved, the step returns SKIPPED with justification.

If ageGated=true, verifies that the TOS documents age-verification requirements and double opt-in. Evaluates only policy language not the full age-gate implementation.

Checks that the TOS contains or links to a prohibition on sharing subscriber data with third parties for marketing purposes, and that the TOS links to the privacy policy

termsOfServiceUrl, legalName, businessWebsiteUrl, ageGated

brand_online_presence_check

opt_in_method_check

Validates the opt-in description for completeness against optInMethod and checks that all declared image URLs are publicly accessible. The description must clearly explain how and where consent is collected, including a direct URL for web-based opt-in flows. PAPER_FORM and IMPORT methods cannot be automatically evaluated and returns SKIPPED with a justification in the response.

If SMS_KEYWORD =true, checks that the keyword appears in the optInDescription.

If mixedUseCase=true, checks that separate opt-in descriptions exist for each declared use case and that they are substantively different from each other. Also evaluates the production message content for signals of multiple message types that would contradict a mixedUseCase=false declaration.

optInMethod, optInDescription, optInImageUrls,optInUrl, optInKeywords, verbalOptInScript, mixedUseCase, useCase1Description, useCase2Description, optInDescription2, sampleMessage

opt_in_message_check

Checks that the opt-in confirmation message — the auto-reply sent to subscribers who opt in via SMS keyword — contains all five CTIA-required disclosure elements. Verifies that the brand is clearly identified using either the legal name or DBA name. Checks that the message instructs the subscriber how to get help (HELP keyword or equivalent). Checks that the message instructs the subscriber how to opt out (STOP keyword or equivalent).

Checks that the message discloses message frequency (e.g., "msg frequency varies" or a specific count).

Checks that the message includes the "message and data rates may apply" disclosure.

optInMessage, legalName, dbaName, optInKeywords

opt_out_message_check

Checks that the STOP response message contains the brand name and clearly confirms the user has been unsubscribed with no further messages sent.

optOutMessage, legalName

help_message_check

Evaluates whether the HELP response contains appropriate brand identification and a meaningful support contact. Evaluates whether the message would reasonably help a recipient find support.

helpMessage, legalName, businessWebsiteUrl

brand_online_presence_check

use_case_consistency_check

Checks that the use case summary, production message content, and website describe a consistent messaging program.

Cross checks reported message volume is consistent with selected use case.

When POLITICAL_ELECTION_CAMPAIGN is included in useCase, the findings field will indicate the requirement of a CV token for submission..

useCase, useCaseSummary, sampleMessage, messageVolume, businessWebsiteUrl

prohibited_use_case_check

Checks website content and useCaseSummary for prohibited use case signals: payday and short-term lending, cryptocurrency trading, MLM and pyramid schemes, debt relief services, third-party debt collection, high-risk financial content, affiliate marketing / lead generation signals and third-party job board references. Also checks for NMLS license number.

businessWebsiteUrl, useCaseSummary, directLending, affiliateMarketing, sampleMessage

shaft_content_check

Screens website content and the production message for signals across SHAFT categories: Sex, Hate, Alcohol, Firearms, Tobacco/Vape, Cannabis/CBD. .

businessWebsiteUrl, sampleMessage, ageGated


Scoring and Results

The callback delivers a primary analysisResult status: PASS, FAIL, or ERROR.

  • PASS: The PreCheck successfully passed analysis. The callback returns an analysisScore (0-100), and analysisIssues will be null. Currently, any score above 80 triggers a PASS.
  • FAIL: The PreCheck failed compliance analysis. An analysisScore (0-100) is provided, and analysisIssues will populate with an array of identified compliance violations.
  • ERROR: An internal system error prevented the analysis from completing. The callback includes an errorCode and errorMessage. Note: Treat this as a processing error, not a compliance failure. Simply re-run the PreCheck once the error has been resolved.

External Project IDs

You can optionally append an externalProjectId string to your PreCheck API payload. Use this field to map our system to your internal CRM, tracking, or database IDs. The API will mirror this identical externalProjectId value back to you within your webhook callback payload.


Authentication

  • Inbound Requests:Authenticate all requests to the PreCheck endpoint (see Request Authentication).

  • Outbound Callbacks: The callback to your system will be signed using the same shared secret (your API key) for HMAC verification. See Webhook Authentication for details.