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
POSTwith JSON body containing brand, agent, and messaging details- Specify which
analysisStepsto run - Include a
callbackUrlwhere 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 PayloadOn success, the API returns:
-
projectId(TexterID project ID. Each PreCheck API call creates a newprojectId.) -
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.site — https://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 |
|---|---|---|---|---|
| Verifies the submitted EIN and business information align with public records. POC Name and Address may be included in the 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. |
| — | — |
| Verifies that the POC email address uses a domain consistent with the submitting organization's website. |
|
| |
| 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. |
|
| |
| 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 |
|
| |
| 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. |
| ||
| 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. |
| ||
| 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 | ||
| 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. |
|
| |
| 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.. |
| ||
| 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. |
| ||
| Screens website content and the production message for signals across SHAFT categories: Sex, Hate, Alcohol, Firearms, Tobacco/Vape, Cannabis/CBD. . |
|
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.
Updated 3 days ago