A2P 10DLC Registration

Register your messaging traffic by creating a brand, registering a campaign, and associating your sending phone numbers with that campaign.

A brand identifies the business responsible for the messages. A campaign describes the messaging use case, sample messages, and how recipients opt in and receive help or opt out.

Before you begin

Use your TextGrid account credentials as described in Getting Started with TextGrid. Brands are associated with the account used to authenticate the request.

All endpoint paths on this page are relative to:

https://api.textgrid.com/2010-04-01

Registration request bodies use Content-Type: application/json. See the API Reference for the complete request and response fields for each operation.

Have your business information, messaging use case, sample messages, opt-in process, privacy policy URL, and terms and conditions URL ready. Required information varies by entity type and use case.

Registration charges

Brand and campaign registration, vetting, appeals, and related registration services may incur charges. Review the pricing applicable to your account before submitting a request. Do not assume these operations are free or that a charge depends on approval.

Avoid submitting duplicate requests while waiting for a result, as additional submissions may incur additional charges.

1. Choose the registration options

Retrieve supported values rather than maintaining your own fixed lists:

Choose a supported business entity type that matches the business and the use case that describes the messages you will send.

2. Create the brand

Submit your business information to:

POST /campaigns/brand/nonblocking

Use the fields and entity-specific requirements in the API Reference. Save the returned brandId; subsequent verification and campaign operations use it.

This operation is nonblocking: a successful creation response does not mean all identity verification has finished. Retrieve the brand to check its current information and identityStatus:

GET /campaigns/brand/{brandId}

You can also list your account's brands with GET /campaigns/brand.

If the brand is unverified

A brand can be returned with an UNVERIFIED identity status. If this happens, you will need to submit a Brand Identity Appeal with the CP575 letter from the IRS. Brand Identity Appeals can currently only be submitted through the dashboard, not through the API.

Review the brand's verification result in the dashboard and submit the appeal there before continuing with campaign registration. Appeal charges may apply; review the applicable pricing before submitting.

3. Complete brand vetting when required

Some brands or use cases require additional vetting. The API supports:

Consult the API Reference for the applicable provider identifiers, vetting class, and import credentials. Account permission and balance requirements can apply. Submit vetting requests only when needed for your registration.

4. Check use-case eligibility

Before creating a campaign, check whether the brand is eligible for your intended use case:

GET /campaigns/brand/{brandId}/usecase/{usecase}

Use a value returned by the use-case enumeration endpoint. Review the eligibility result and resolve verification or vetting requirements before proceeding.

5. Create the campaign

Submit the campaign to:

POST /campaigns/campaign

Key fields include:

Also provide the applicable content declarations and opt-in, opt-out, and help settings documented in the API Reference. Required values depend on the brand, use case, and registration review; the fields above are not a complete minimum request.

Save the returned campaignId. Creating a campaign does not enable your phone numbers to send messages. The campaign must receive the required approval, and you must attach your sending phone numbers to it as described in Step 7 before they can send campaign traffic.

Attach supporting media

When supporting material is needed, use:

These endpoints accept JSON with File, FileName, and MimeType. File contains Base64-encoded file content; do not send it as a multipart upload.

6. Monitor registration status

Retrieve the campaign to check its current status and registration details:

GET /campaigns/campaign/{campaignId}

You can also list campaigns for a brand:

GET /campaigns/brand/{brandId}/campaign

If review identifies an issue, correct the campaign information using the appropriate operation:

Follow the returned review information rather than repeatedly creating replacement brands or campaigns.

Receive registration webhooks

Configure your account's registration webhook URL through the TextGrid Dashboard to receive event notifications. TextGrid sends a POST request with:

• Content-Type: application/json.
• A TCREvent query parameter identifying the event.
• An X-TextGrid-Signature header for signature verification.

For example, a configured URL of https://example.com/registration receives requests shaped like:

POST /registration?TCREvent=EXAMPLE_EVENT
Content-Type: application/json
X-TextGrid-Signature: <signature>

EXAMPLE_EVENT is a placeholder, not a documented event name. Treat event names as strings and allow additional event-specific fields and null values in the JSON body.

Verify the signature before processing the event. For these POST requests, the signing URL includes the TCREvent query parameter, followed directly by the unchanged raw JSON body. See Verifying Webhook Signatures for the complete algorithm and samples.

Return HTTP 200 to acknowledge the notification. The sender makes one request and logs non-200 results; it does not provide an automatic retry loop. Make processing tolerant of duplicate events, and use the brand and campaign retrieval endpoints to reconcile current status.

7. Attach sending phone numbers

After the campaign has the required approval and eligibility, associate your sending numbers with it:

POST /campaigns/number/{campaignId}

Supply TextGrid phone-number SIDs in the phoneNumberSids array, rather than phone-number strings:

{
  "phoneNumberSids": [
    "EXAMPLE_PHONE_NUMBER_SID"
  ]
}

Replace the fictitious SID with one belonging to the authenticated account. Do not send a null array.

Allow time for number attachment

Attaching a phone number to a campaign is not instant. It usually completes within a few minutes, but can take up to a few days, especially when requested over a weekend or legal holiday.

A successful attachment request does not mean the number is ready to send campaign traffic. Wait for attachment to complete and confirm the number's association before sending. Do not repeatedly submit the attachment request while it is processing.

Confirm the association using:

Check the returned association and registration results before using the numbers for campaign traffic. Registration and number attachment do not guarantee delivery of every message.

Maintain your registration

Keep brand and campaign information aligned with the business and messages being sent. Recheck eligibility when changing the messaging use case.

To remove a number from a campaign, use DELETE /campaigns/number/{phoneNumberSid}. To deactivate a campaign, use DELETE /campaigns/campaign/{campaignId}. Review the effect on your sending numbers before making either change.