Create and activate sub-account profiles via the API

Choose inheritance, sharing, and billing settings

Decide these before creating the profile: they determine which resources the sub-account shares with your organization and who pays for its messaging.

Inheritance and sharing flags:

If your tenants must not see each other's data, set inherit_contacts and inherit_templates to false and leave the sharing flags off. If your tenants are brands that need their own US A2P registration, set inherit_tcr_brand and inherit_tcr_campaign to false and supply a brand object in the create request (next step). To run all tenants under your own registration, keep the defaults.

Billing model (billing_model, default profile):

Use organization when your platform absorbs messaging costs and invoices tenants itself. Use profile when each tenant pays Sent directly. Use profile_and_organization when tenants pay directly but you guarantee their usage. With profile or profile_and_organization you may also pass payment_details (card number, MM/YY expiry, CVC, ZIP code); card details are never stored on Sent's servers and are forwarded directly to the payment processor. Passing payment_details with billing_model: "organization" is rejected.

Create the profile

Send POST /v3/profiles. Only name is required to create, but set short_name (3–11 characters: letters, numbers, and spaces, with at least one letter) and description now: the completion step in this guide rejects profiles that lack them.

For a tenant with its own TCR brand and direct billing:

curl -X POST "https://api.sent.dm/v3/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",
    "description": "Sender profile for tenant 42",
    "inherit_contacts": false,
    "inherit_templates": false,
    "inherit_tcr_campaign": false,
    "billing_model": "profile",
    "billing_contact": {
      "name": "Tenant 42 Coffee Co",
      "email": "billing@tenant42.example.com",
      "phone": "+12025551234",
      "address": "123 Main Street, New York, NY 10001, US"
    },
    "brand": {
      "contact": {
        "name": "Jane Doe",
        "businessName": "Tenant 42 Coffee Co",
        "email": "jane@tenant42.example.com"
      },
      "business": {
        "legalName": "Tenant 42 Coffee Company LLC",
        "country": "US"
      },
      "compliance": {
        "vertical": "PROFESSIONAL",
        "brandRelationship": "SMALL_ACCOUNT",
        "isTcrApplication": true
      }
    }
  }'

Providing brand implicitly sets inherit_tcr_brand to false; it cannot be combined with inherit_tcr_brand: true. If you keep the organization's registration instead, omit brand and the inheritance flags, but read the callout in the next step first.

If the profile needs its own WhatsApp Business Account, add direct credentials to the request body:

"whatsapp_business_account": {
  "waba_id": "123456789012345",
  "phone_number_id": "987654321098765",
  "access_token": "EAAxxxxxxxxxxxxxxx"
}

Omit the field to inherit the organization's WhatsApp Business Account instead. If you omit it and the organization has not completed WhatsApp Embedded Signup, the request fails with HTTP 422.

A successful request returns 201 with the profile in data, including its id (every later call needs it) and "status": "incomplete". The Idempotency-Key header makes retries safe; responses are cached for 24 hours per key. Refer to the create profile reference for the full field list.

Start completion with a webhook URL

Completion validates the profile, connects it to the SMS and WhatsApp providers, and sets its final status. It runs in the background, so the request requires a webHookUrl that Sent calls when processing finishes, on success or failure:

curl -X POST "https://api.sent.dm/v3/profiles/$PROFILE_ID/complete" \
  -H "x-api-key: $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webHookUrl": "https://your-app.example.com/webhooks/profile-complete"
  }'

A 202 response ("Profile completion in progress") means validation passed and processing started. A 200 means the profile was already completed; the body contains its current status. A 400 means a prerequisite failed: the profile needs name, short_name, and description set, its own KYC submission, an available TCR brand (its own or the organization's), and, for TCR applications, at least one campaign, either inherited or created with POST /v3/profiles/{profileId}/campaigns.

Handle the completion callback

When the background process finishes, Sent sends a POST request with a JSON body to your webHookUrl:

{
  "profileId": "770e8400-e29b-41d4-a716-446655440002",
  "success": true,
  "status": "COMPLETED",
  "timestamp": "2026-07-25T14:03:11.402Z"
}

COMPLETED means the profile is fully activated. SUBMITTED means processing finished but the profile is not yet sendable. The profile lands there when either the SMS or WhatsApp channel configuration is missing, when a dedicated (non-inherited) TCR brand or campaign has not yet been submitted to TCR, or when a non-TCR profile declares a main destination country, which requires more information before activation.

A minimal receiver:

app.post("/webhooks/profile-complete", (req, res) => {
  res.sendStatus(200);

  const { profileId, success, status } = req.body;
  if (success) {
    // status is "COMPLETED" (ready) or "SUBMITTED" (pending registration/config)
    markTenantProvisioned(profileId, status);
  } else {
    // status is "failed", retry the complete call or investigate
    flagTenantProvisioningFailure(profileId);
  }
});

Sent calls the webhook once and does not retry. If your endpoint misses the callback, poll the profile status (next step) instead.

Verify the profile

Confirm the outcome with GET /v3/profiles/{profileId}:

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

The status field reports the public setup state: approved corresponds to the COMPLETED webhook status, submitted to SUBMITTED, processing means completion is still running, and failed means it did not finish. To see the profile in context, call GET /v3/me with your organization key: the profiles array lists every child profile with its status and the calling user's role in it.

Operate on the child profile

To call any /v3 endpoint as the new profile, add the x-profile-id header to a request made with your organization API key:

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"}
  }'

The request executes as the profile (its templates, contacts, numbers, and settings apply) and the response echoes the scope in an X-Profile-Id header. Only organization API keys can use x-profile-id; profile-scoped keys are rejected with 403, and a profile ID outside your organization returns 404. If you prefer to hand tenants their own credentials instead of proxying through your organization key, each profile also has its own API key. See API credentials and isolation.