sinch-10dlc

What this skill does

# Sinch 10DLC Registration

## Overview

10DLC (10-Digit Long Code) is the required US registration system for Application-to-Person (A2P) SMS on standard 10-digit phone numbers. You must register a **brand** (the sending company) and a **campaign** (the messaging use case) with The Campaign Registry (TCR) via Sinch before sending any US A2P SMS.

## Agent Instructions

Before generating code, gather from the user (skip any item already specified in the prompt or context):

1. **Goal** — register a brand, register a campaign, check status, or troubleshoot a rejection?
2. **Brand ID?** — if the user already has one, skip to Step 3 (qualify) or Step 4 (campaign).
3. **Registration type** — `SIMPLIFIED` (faster, lower throughput, $10) or `FULL` (recommended for production, $50)?
4. **Language** — any language, or curl. This API is REST-only; there is no SDK wrapper. Use curl, `fetch`, `axios`, `requests`, or equivalent HTTP clients.

This skill covers **10DLC only**. The same Registration API also includes TFN (Toll-Free Number) verification endpoints — for toll-free registration, see the API spec directly.

Refer to the API reference linked in Links for request/response schemas.

**Security**: See the Security section below for url fetching policy and credential handling.

## Getting Started

### Agent Credentials handling

Store credentials in environment variables — never hardcode tokens or keys in commands or source code:

```bash
export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"
export SINCH_ACCESS_TOKEN="your-oauth-token"
```

### Authentication

Ensure that authentication headers are properly set when making API calls. The 10DLC API uses Bearer token authentication:

```bash
-H "Authorization: Bearer $SINCH_ACCESS_TOKEN"
```

See [sinch-authentication](../sinch-authentication/SKILL.md) for full setup, most importantly how to obtain `{SINCH_ACCESS_TOKEN}` (OAuth2 client-credentials — do not mint your own JWT).

### Base URL

```
https://us10dlc.numbers.api.sinch.com
```

US-only — there are no regional variants for 10DLC.

### First API Call

Register a brand:

```bash
curl -X POST \
  "https://us10dlc.numbers.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/brandRegistrations:submit" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "brandRegistrationType": "FULL",
  "displayName": "Sinch Mock",
  "companyDetails": {
    "companyName": "Sinch",
    "brandName": "Sinch Mock x",
    "companyEmail": "[email protected]",
    "country": "US",
    "state": "GA",
    "city": "Atlanta",
    "streetAddress": " 3500 Lenox Rd NE, Ste. 1875",
    "postalCode": "94105",
    "webAddress": "https://sinch.com"
  },
  "financialDetails": {
    "brandEntityType": "PRIVATE",
    "brandVerticalType": "TECHNOLOGY",
    "taxIdCountry": "US",
    "taxIdCorporate": "770505044",
    "stockSymbol": "SINCH",
    "exchange": "STO"
  },
  "contactDetails": {
    "firstName": "Jane",
    "lastName": "Doe",
    "phoneNumber": "+14155550100",
    "email": "[email protected]"
  },
  "mock": true
}'
```

## Key Concepts

- **Brand** — The company sending messages. Must be registered first. ID starts with `B` (e.g., `BESINCH`).
- **Campaign** — A messaging use case tied to a brand. Defines what, to whom, and why.
- **TCR** — The Campaign Registry. Sinch submits to TCR on your behalf as your CSP.
- **Registration type** (`brandRegistrationType`) — `SIMPLIFIED` (basic, lower throughput, $10) or `FULL` (complete vetting, higher throughput, $50). Default is `SIMPLIFIED`. Prefer `FULL` for production.
- **Trust score** — Assigned by TCR after vetting. Higher score = more messages per second. This is a TCR concept; the Sinch API does not return it in the brand response.
- **Use case** — The campaign's messaging purpose. Use cases are categorized as Standard or Special, with different vetting requirements and fees.
  - Standard Use Cases: 2FA, ACCOUNT_NOTIFICATION, CUSTOMER_CARE, DELIVERY_NOTIFICATION, FRAUD_ALERT, HIGHER_EDUCATION, MARKETING, POLLING_VOTING, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT.
  - Special Use Cases: AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, EMERGENCY, K12_EDUCATION, POLITICAL, PROXY, SOCIAL, SWEEPSTAKE.
  - Mixed/Low Volume: LOW_VOLUME or MIXED can be used for campaigns that combine multiple standard use cases but have low traffic requirements.
- **CSP** — Campaign Service Provider. Sinch typically acts as your CSP, managing the registration process. It's also possible for you to register as your own CSP directly with TCR and use Sinch for number provisioning and connectivity, though this is a more advanced setup.

## Workflow: Complete 10DLC Setup

Follow these steps in order. Each step depends on the previous one succeeding. For detailed curl examples, response schemas, enum values, and polling strategies, see [references/workflow.md](references/workflow.md).

**Once approved**, you can send A2P SMS on US 10-digit long codes through Sinch. To send messages, see the [sinch-conversation-api](../sinch-conversation-api/SKILL.md) skill.

## Common Patterns

- **List all brands/campaigns** — See [List All Brands](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-brand-registration/brandregistrationservice_listbrandregistrationrequest.md) and [List All Campaigns](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-campaign-registration/campaignregistrationservice_listcampaignregistrationrequest.md)
- **Upgrade brand from Simplified to Full** — See [Upgrade Brand](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-brand-registration/brandregistrationservice_upgrade10dlcbrandtofullregistration.md)
- **Update brand details** — See [Update Brand Registration](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-brand-registration/brandregistrationservice_update10dlcbrand.md)
- **Look up brand by TCR ID** — See [Get Brand by TCR Brand ID](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-brand-registration/brandregistrationservice_fetchbrandregistrationrequest.md)
- **Look up campaign by TCR ID** — See [Get Campaign by TCR Campaign ID](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-campaign-registration/campaignregistrationexternalservice_getcampaignbytcrcampaignid.md)
- **Delete a campaign** — See [Delete Campaign](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-campaign-registration/campaignregistrationexternalservice_deletecampaign.md) (irreversible, status becomes `EXPIRED`). **Note:** the delete path uses singular `campaignRegistration` (not plural) — `DELETE /v1/projects/{projectId}/campaignRegistration/{campaignRegistrationId}`
- **Resubmit a campaign** — See [Resubmit Campaign](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-campaign-registration/campaignregistrationservice_resubmitcampaignregistration.md). After resubmitting, poll `lastActionStatus`: `RESUBMIT_IN_PROGRESS` → `RESUBMIT_SUCCESSFUL` (get updated MNO metadata) or `RESUBMIT_FAILED` (check campaign feedback for reason)
- **Get brand vetting info** — See [Brand Vetting Information](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-brand-registration/brandregistrationservice_getbrandregistrationvettinginfo.md)
- **Resend 2FA email** — See [Resend 2FA Email](https://developers.sinch.com/docs/10dlc-registration/api-reference/10dlc-registration/10dlc-brand-registration/brandregistrationservice_resend2faemail.md)

## Gotchas and Best Practices

### Brand rejected

1. Fetch brand feedback (see Step 2 above)
2. Common fixes: correct EIN format (`XX-XXXXXXX`), match company name to IRS records exactly, fix stock symbol if