/telnyx-10dlc-curl

name: telnyx-10dlc-curl
description: >-
  10DLC brand and campaign registration for US A2P messaging compliance. Assign
  phone numbers to campaigns.
metadata:
  author: telnyx
  product: 10dlc
  language: curl
  generated_by: telnyx-openapi-pipeline
  contract: v2

<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx 10DLC - curl

Installation

# curl is pre-installed on macOS, Linux, and Windows 10+

Setup

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use `$TELNYX_API_KEY` for authentication.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entityType": "PRIVATE_PROFIT",
  "displayName": "ABC Mobile",
  "country": "US",
  "email": "support@example.com",
  "vertical": "TECHNOLOGY"
}' \
  "https://api.telnyx.com/v2/10dlc/brand"

Common error codes: `401` invalid API key, `403` insufficient permissions, `404` resource not found, `422` validation error (check field formats), `429` rate limited (retry with exponential backoff).

Important Notes

• **Pagination:** List endpoints return paginated results. Use `page[number]` and `page[size]` query parameters to navigate pages. Check `meta.total_pages` in the response.

Operational Caveats

• 10DLC is sequential: create the brand first, then submit the campaign, then attach messaging infrastructure such as the messaging profile.
• Registration calls are not enough by themselves. Messaging cannot use the campaign until the assignment step completes successfully.
• Treat registration status fields as part of the control flow. Do not assume the campaign is send-ready until the returned status fields confirm it.

Reference Use Rules

Do not invent Telnyx parameters, enums, response fields, or webhook fields.

• If the parameter, enum, or response field you need is not shown inline in this skill, read [references/api-details.md](references/api-details.md) before writing code.
• Before using any operation in `## Additional Operations`, read [the optional-parameters section](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas).
• Before reading or matching webhook fields beyond the inline examples, read [the webhook payload reference](references/api-details.md#webhook-payload-fields).

Core Tasks

Create a brand

Brand registration is the entrypoint for any US A2P 10DLC campaign flow.

`POST /10dlc/brand`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `entityType` | object | Yes | Entity type behind the brand. | | `displayName` | string | Yes | Display name, marketing name, or DBA name of the brand. | | `country` | string | Yes | ISO2 2 characters country code. | | `email` | string | Yes | Valid email address of brand support contact. | | `vertical` | object | Yes | Vertical or industry segment of the brand. | | `companyName` | string | No | (Required for Non-profit/private/public) Legal company name. | | `firstName` | string | No | First name of business contact. | | `lastName` | string | No | Last name of business contact. | | ... | | | +16 optional params in [references/api-details.md](references/api-details.md) |

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entityType": "PRIVATE_PROFIT",
  "displayName": "ABC Mobile",
  "country": "US",
  "email": "support@example.com",
  "vertical": "TECHNOLOGY"
}' \
  "https://api.telnyx.com/v2/10dlc/brand"

Primary response fields:

• `.data.brandId`
• `.data.identityStatus`
• `.data.status`
• `.data.displayName`
• `.data.state`
• `.data.altBusinessId`

Submit a campaign

Campaign submission is the compliance-critical step that determines whether traffic can be provisioned.

`POST /10dlc/campaignBuilder`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `brandId` | string (UUID) | Yes | Alphanumeric identifier of the brand associated with this ca... | | `description` | string | Yes | Summary description of this campaign. | | `usecase` | string | Yes | Campaign usecase. | | `ageGated` | boolean | No | Age gated message content in campaign. | | `autoRenewal` | boolean | No | Campaign subscription auto-renewal option. | | `directLending` | boolean | No | Direct lending or loan arrangement | | ... | | | +29 optional params in [references/api-details.md](references/api-details.md) |

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "brandId": "BXXXXXX",
      "description": "Two-factor authentication messages",
      "usecase": "2FA",
      "sample1": "Your verification code is {{code}}"
  }' \
  "https://api.telnyx.com/v2/10dlc/campaignBuilder"

Primary response fields:

• `.data.campaignId`
• `.data.brandId`
• `.data.campaignStatus`
• `.data.submissionStatus`
• `.data.failureReasons`
• `.data.status`

Assign a messaging profile to a campaign

Messaging profile assignment is the practical handoff from registration to send-ready messaging infrastructure.

`POST /10dlc/phoneNumberAssignmentByProfile`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `messagingProfileId` | string (UUID) | Yes | The ID of the messaging profile that you want to link to the... | | `campaignId` | string (UUID) | Yes | The ID of the campaign you want to link to the specified mes... | | `tcrCampaignId` | string (UUID) | No | The TCR ID of the shared campaign you want to link to the sp... |

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{