Create and activate Sender Profiles via the API

This guide shows you how to provision a Sender Profile through the API: create it, decide which resources are dedicated to it and which are inherited, give it a sender, and read what its compliance still owes. It is written for platforms and resellers that onboard tenants programmatically; for the dashboard flow, see Creating a Sender Profile, and for choosing between shared and per-tenant architectures, see Multi-Tenant Architectures.

Before you start, you need:

• An organization account. Call GET /v3/me: the response type must be organization.
• An organization API key whose user has the admin role in the organization. See roles and permissions for how roles are granted.

All requests authenticate with the x-api-key header.

The minimum request

A profile needs a name and a short name. Everything else (identity, inbox, opt-out list, billing) comes from your organization, so the profile is usable immediately with no compliance work:

curl -X POST "https://api.sent.dm/v3/sender-profiles" \
  -H "x-api-key: $ORG_API_KEY" \
  -H "Idempotency-Key: create-profile-tenant-42" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tenant 42 Coffee Co",
    "short_name": "T42COFFEE"
  }'

The response carries the profile, its id, and its api_key. The key is shown once, by create, and is never returned again. Store it before you discard the response. Reads never include it.

The status code tells you whether anything is still in flight:

Neither is an error, and neither needs a callback: there is no completion step to run and nothing to wait for before the profile is usable.

Dedicated, inherited, or absent

Every capability is one of three things, and there is no flag per state:

There is no "inherit": false that also carries no data: a second way to say the same thing would let a request contradict itself. Inheriting needs no id, because a customer has exactly one brand.

A sender is the exception. A brand and a campaign can be inherited; a number cannot. A profile either has a dedicated sender, through channels.sms, or it has none and terminates through the shared routes for that country.

Billing

{ "billing": { "inherit": true } }

Omit billing and nothing is opted into: the profile stays on the storage default, where the profile pays. { "inherit": true } bills the organization. fallback draws on the organization's balance when the profile's runs out, and cannot be combined with inherit: true. Inheriting already bills the organization, so the pair is refused rather than silently resolved.

Giving the profile a sender

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

curl -X POST "https://api.sent.dm/v3/sender-profiles" \
  -H "x-api-key: $ORG_API_KEY" \
  -H "Idempotency-Key: create-profile-tenant-42" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tenant 42 Coffee Co",
    "short_name": "T42COFFEE",
    "billing": { "inherit": true },
    "channels": {
      "sms": { "country": "US", "number_type": "TEN_DLC" }
    },
    "compliance": {
      "brand": { "inherit": true },
      "campaign": { "inherit": true }
    }
  }'

curl "https://api.sent.dm/v3/sender-profiles/$PROFILE_ID" \
  -H "x-api-key: $ORG_API_KEY"

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": { "tax_id": "12-3456789" } } }'

curl -X POST "https://api.sent.dm/v3/messages" \
  -H "x-api-key: $ORG_API_KEY" \
  -H "x-profile-id: $PROFILE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+15551234567"],
    "template": {"id": "tmpl_123"}
  }'

Listing, updating, and deleting

List with GET /v3/sender-profiles, newest first. page and page_size are both required. Each entry is the same document a single read returns, with one difference: listed markets carry no compliance. Working out what a market owes means a catalog lookup and a document read per market, and doing that for every profile on a page would turn one request into dozens to answer a question you did not ask. Read a single profile for that.

compliance being absent is not the same as it being empty. Absent means it was not worked out here; empty means the market owes nothing.

Update with PATCH /v3/sender-profiles/{id}, which changes name, short_name, and description, and only those. A profile's identity, its markets, and its compliance each have a separate sub-resource, because each has its own validation and external consequences: a brand change may need re-registering, a market change provisions a sender. Omitting a field leaves it alone and sending null clears it, so {} is refused rather than returning a 200 and an unchanged profile. name and short_name cannot be cleared.

Delete with DELETE /v3/sender-profiles/{id}, which returns 204. The delete is soft: the profile stops being usable and stops appearing in reads, and its message history is kept, because deleting a profile must not delete the record of what it sent. Anything the profile still held goes with it: a phone number returns to our inventory and can be given to whoever asks next, and a dedicated WhatsApp account is deregistered from Meta. A profile that only inherits holds nothing dedicated, so it releases nothing.

Migrating from /v3/profiles

The /v3/profiles endpoints and the profile-campaign endpoints under them are deprecated. They still work, so nothing breaks today, but new integrations should use /v3/sender-profiles.

Six fields on the old endpoints are now accepted and ignored, and are worth checking for in existing code because a request carrying them still succeeds:

These were bound rather than removed so an SDK that assigns them keeps compiling. Nothing is refused, because a 400 would break an integration that is otherwise working. Even so, a caller that reads back what it wrote can see it did not take.

Troubleshooting

Related pages

• Sender Profiles - which resources are dedicated and which are inherited
• Managing channels - adding SMS markets, WhatsApp, and RCS to a profile
• Creating a Sender Profile - the dashboard flow
• Multi-Tenant Architectures - choosing shared versus per-tenant setups
• 10DLC Registration - registering for US SMS
• Refer to the create, list, read, update, and delete Sender Profile references for every field and response