Managing channels

Ask what the market wants

Call GET /v3/compliance/requirements before you add a market. It returns what that market demands, and setup[] — the calls that satisfy it, each with a body you can copy and send as it stands:

curl "https://api.sent.dm/v3/compliance/requirements?channel=sms&country=US&type=TEN_DLC" \
  -H "x-api-key: $SENT_API_KEY"

There is always exactly one setup step, POST /v3/channels/sms, because the identity travels in that call's body rather than needing a separate call. Anything that cannot be a JSON value, such as an uploaded document, is listed under attachments instead of in the body template.

Requirements vary enormously. US TEN_DLC registers a brand and a campaign with The Campaign Registry and asks for a substantial set of values; an alphanumeric sender pre-registers with supporting documents in one country and needs nothing at all in another. This is the same declaration that validates the calls themselves, so it cannot drift from what the API accepts.

Add the market

POST /v3/channels/sms gives the sender a market — the first one it sends in, and the fifth:

curl -X POST "https://api.sent.dm/v3/channels/sms" \
  -H "x-api-key: $ORG_API_KEY" \
  -H "x-profile-id: $PROFILE_ID" \
  -H "Idempotency-Key: add-us-tendlc-tenant-42" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "number_type": "TEN_DLC",
    "compliance": {
      "brand": {
        "legal_name": "Tenant 42 Coffee Company LLC",
        "business_name": "Tenant 42 Coffee Co",
        "tax_id": "12-3456789",
        "tax_id_type": "us_ein",
        "entity_type": "PRIVATE_PROFIT",
        "street": "123 Main Street",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US",
        "contact_name": "Jane Doe",
        "contact_email": "jane@tenant42.example.com",
        "contact_phone": "+12125550123"
      },
      "campaign": {
        "description": "Order and delivery updates for coffee subscriptions",
        "message_flow": "Customers opt in at checkout on tenant42.example.com by ticking a box that is unchecked by default. Consent is not a condition of purchase.",
        "use_cases": [
          {
            "use_case": "DELIVERY_NOTIFICATION",
            "sample_messages": ["Tenant 42 Coffee: your order #1234 ships today. Reply STOP to opt out."]
          }
        ],
        "opt_in_keywords": "START,YES",
        "opt_out_keywords": "STOP",
        "help_keywords": "HELP",
        "opt_in_message": "Tenant 42 Coffee: you are subscribed to order updates. Reply STOP to opt out, HELP for help.",
        "opt_out_message": "Tenant 42 Coffee: you will receive no further messages.",
        "help_message": "Tenant 42 Coffee: for help, email support@tenant42.example.com. Reply STOP to opt out.",
        "privacy_policy_link": "https://tenant42.example.com/privacy",
        "terms_and_conditions_link": "https://tenant42.example.com/terms"
      }
    }
  }'

Everything the regime wants arrives in 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, and nothing is submitted by this call — the rows are what a submission is later assembled from, and filing happens externally.

Send { "inherit": true } in place of either object to run on your organization's:

{
  "country": "US",
  "number_type": "TEN_DLC",
  "compliance": {
    "brand": { "inherit": true },
    "campaign": { "inherit": true }
  }
}

A few field rules worth knowing before you fill the template in:

• campaign.message_flow is the consent narrative in prose. Under 40 characters is refused, and carriers reject vague descriptions — say where opt-in happens, that the box is unchecked by default, and that consent is not a condition of purchase.
• campaign.use_cases takes one to five entries, each with one to five sample messages. MIXED and LOW_VOLUME are refused as use cases: campaign.volume decides those. Omitting volume registers the campaign at the higher-fee standard tier.
• sender_value is only for the types where you choose the sender rather than the carrier assigning it — an alphanumeric sender id, a short code, or a number you already own. Omit it for carrier-assigned types and one is provisioned.

Read one market

GET /v3/channels/sms/{country}/{type} reads one market — its sender, where that sender stands, and everything its compliance holds:

curl "https://api.sent.dm/v3/channels/sms/us/ten_dlc" \
  -H "x-api-key: $ORG_API_KEY" \
  -H "x-profile-id: $PROFILE_ID"

A market that registers with a compliance regime reports brand and campaign, each carrying inherit to say whether it is yours or your organization's.

A market that registers with nobody has neither, so both keys are absent rather than null. Absent says this market does not ask; null would say it asks and you supplied nothing. It reports documents instead.

requirements lists what is still owed, keyed as you write it. GET /v3/compliance/requirements says what a market demands of anybody; this says what you gave it.

Correct what it holds

PATCH /v3/channels/sms/{country}/{type} takes the compliance object from the read straight back:

curl -X PATCH "https://api.sent.dm/v3/channels/sms/us/ten_dlc" \
  -H "x-api-key: $ORG_API_KEY" \
  -H "x-profile-id: $PROFILE_ID" \
  -H "Content-Type: application/json" \
  -d '{ "compliance": { "brand": { "contact_phone": "+12125550123" } } }'

Partial at every level. An omitted key is left alone; an explicit null clears it. Those are different requests, so {} changes nothing and is refused rather than silently accepted, and correcting one field does not blank the others. A requirements key is the path into the body that clears it.

Nothing here creates a second anything — one identity and one campaign per market — so a write is an upsert and a replayed request lands on the row it already wrote. There is no sub-resource for either half: both are singletons of the market, so both are written here.

The response is the market as stored, in the same shape GET returns, so what comes back can be sent back.