Gives the customer a sender in one country — the first market it sends in, and the fifth.

What to have in place first

Call GET /v3/compliance/requirements?country=US&type=TEN_DLC first. It returns this request's body ready to fill in, plus the brand and campaign calls to make before it, in order. You never have to track forty countries' rules yourself.

A market that registers with a compliance regime needs an identity, and this call takes one. US TEN_DLC registers with The Campaign Registry and files that registration against a business identity. Send it in compliance.brand and it is recorded here, before the registration that attaches to it — so a customer with no identity reaches a first 10DLC market in one call.

{ "inherit": true } runs on your organization's instead. A market with neither — none stored, none sent — is 400, because accepting it would write a channel that could never register and leave it provisioning for ever with nothing saying why.

Everything the regime wants arrives in this request's compliance, as two declared objects: brand — the identity the registration is filed against — and campaign, with the use case, the consent narrative, the volume, the sample messages and the keywords. There is nothing to set up first. Nothing is submitted here either: the rows are what a submission is later assembled from, and filing is externally rejectable so it happens on its own path.

A half you run yourself has to be complete here. Whichever of brand and campaign is your own rather than your organization's must carry every field the regime asks of it, counting what you already hold — send the rest in this request. A missing one is 400 naming each field, rather than a 202 for a market that could never be filed. A half you inherit is asked for nothing.

A market that registers with nobody — an alphanumeric sender in most countries — needs neither, and may need documents instead.

Sending it

Takes the same fields channels.sms takes on POST /v3/sender-profiles, because it is the same work, and both run one provisioning path. compliance is top-level and answers for the market in this request, carrying brand and campaign where the market registers.

Accepts multipart as well as JSON, with each file named after the compliance key it satisfies — a market that pre-registers its sender needs its documents at the same moment it needs the sender. Every required document must be attached to this request; a missing or invalid file is rejected before the market is added.

area_codes puts the sender somewhere specific, in your order of preference, for a LOCAL sender in any country or a US TEN_DLC sender — a 10DLC number is an ordinary local long code bound to a registered campaign, so both take the same codes out of the same inventory. It is honoured exactly: you get a number in one of the codes you named or you get none, never one in a code you left out.

Several numbers

numbers lists the numbers you want, one entry per area code, e.g. [{"area_code": "212", "quantity": 2}, {"quantity": 1}] for two numbers in 212 and one in any area code. quantity defaults to 1, and an entry without area_code means any area code. Omit numbers for one number. It is for LOCAL and TEN_DLC only and cannot be combined with area_codes. A market holds at most 49 numbers, counting the ones it already has.

On a LOCAL market you already hold, numbers adds those numbers to it instead of 409. US TEN_DLC numbers belong to the market's campaign and are assigned when the campaign is approved, not at request time. Until then they read as PROVISIONING in the response's numbers, each with the area code it was asked for. A profile inheriting your organization's campaign cannot request numbers (400). numbers on a TEN_DLC market you already hold is 409: its numbers belong to its one campaign and are set when the market is created.

A market you already send in is 409: adding what is already there is a mistake worth reporting rather than a silent no-op. A market is a (country, sender_type) pair, so a second sender type in a country you already send in is fine — US TOLL_FREE alongside US TEN_DLC is the ordinary case. Two of the same type is not.

A market you hold that has no sender yet is not a duplicate, and re-sending it re-asks for a sender rather than being refused. That is the way out of an area-code request nothing could fill: send the call again to name different codes, or no codes at all to take a number anywhere in the country. It answers 201 with the sender when the pool has one, otherwise 202 with the codes recorded — and changes nothing else; compliance on a market you hold is PATCH /v3/channels/sms/{country}/{type}.

One exception: while a market's sender type is still unassigned, adding any type to that country is 409 once it has a sender, because the market you have may be about to become the one you asked for.

Returns the market, in the shape GET and PATCH on /v3/channels/sms/{country}/{type} use — so what this answers can be read back and written back without reshaping. Not every channel you have: adding a market cannot change an RCS agent or a WhatsApp account, and GET /v3/channels is the whole picture. 201 when the market is ready; 202 while a sender or a registration is still outstanding.

Send x-profile-id with an organization key to add a market to one of your profiles.

{
  "country": "US",
  "number_type": "TEN_DLC",
  "area_codes": [
    "415",
    "628"
  ],
  "compliance": {
    "brand": {
      "inherit": false,
      "legal_name": "Example Retail Inc",
      "entity_type": "PRIVATE_PROFIT",
      "country": "US",
      "website": "https://example.com"
    },
    "campaign": {
      "inherit": false,
      "description": "Order and delivery updates for customers who opted in at checkout.",
      "message_flow": "Customers opt in at checkout by checking a consent box.",
      "use_cases": [
        {
          "use_case": "DELIVERY_NOTIFICATION",
          "sample_messages": [
            "Your order #1234 has shipped and will arrive tomorrow."
          ]
        }
      ]
    }
  },
  "sandbox": false
}

{
  "data": {
    "status": "PROVISIONING"
  }
}