Create a new profile

Creates a new sender profile within an organization. Profiles represent different brands, departments, or use cases, each with their own messaging configuration and settings. Requires admin role in the organization. ## WhatsApp Business Account Every profile must be linked to a WhatsApp Business Account. There are two ways to do this: **1. Inherit from organization (default)** — Omit the `whatsapp_business_account` field. The profile will share the organization's WhatsApp Business Account, which must have been set up via WhatsApp Embedded Signup. This is the recommended path for most use cases. **2. Direct credentials** — Provide a `whatsapp_business_account` object with `waba_id`, `phone_number_id`, and `access_token`. Use this when the profile needs its own independent WhatsApp Business Account. Obtain these from Meta Business Manager by creating a System User with `whatsapp_business_messaging` and `whatsapp_business_management` permissions. If the `whatsapp_business_account` field is omitted and the organization has no WhatsApp Business Account configured, the request will be rejected with HTTP 422. ## Brand Include the optional `brand` field to create the brand for this profile at the same time. Cannot be used when `inherit_tcr_brand` is `true`. ## Payment Details When `billing_model` is `"profile"` or `"profile_and_organization"` you may include a `payment_details` object containing the card number, expiry (MM/YY), CVC, and billing ZIP code. Payment details are **never stored** on our servers and are forwarded directly to the payment processor. Providing `payment_details` when `billing_model` is `"organization"` is not allowed.

POST
/v3/profiles

Header Parameters

Idempotency-Key?string

Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.

Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255
x-profile-id?string

Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.sent.dm/v3/profiles" \  -H "Idempotency-Key: req_abc123_retry1" \  -H "Content-Type: application/json" \  -d '{    "name": "Sales Team",    "icon": "https://example.com/sales-icon.png",    "description": "Sales department sender profile",    "short_name": "SALES",    "allow_contact_sharing": true,    "allow_template_sharing": false,    "inherit_contacts": true,    "inherit_templates": true,    "inherit_tcr_brand": false,    "inherit_tcr_campaign": false,    "billing_model": "profile",    "billing_contact": {      "name": "Acme Corp",      "email": "billing@acmecorp.com",      "phone": "+12025551234",      "address": "123 Main Street, New York, NY 10001, US"    },    "whatsapp_business_account": {      "waba_id": "123456789012345",      "phone_number_id": "987654321098765",      "access_token": "EAAxxxxxxxxxxxxxxx"    },    "brand": {      "contact": {        "name": "John Smith",        "businessName": "Acme Corp",        "role": "CEO",        "phone": "+12025551234",        "email": "john@acmecorp.com",        "phoneCountryCode": "1"      },      "business": {        "legalName": "Acme Corporation LLC",        "taxId": "12-3456789",        "taxIdType": "us_ein",        "entityType": "PRIVATE_PROFIT",        "street": "123 Main Street",        "city": "New York",        "state": "NY",        "postalCode": "10001",        "country": "US",        "url": "https://acmecorp.com",        "countryOfRegistration": "US"      },      "compliance": {        "vertical": "PROFESSIONAL",        "brandRelationship": "SMALL_ACCOUNT",        "primaryUseCase": "Customer notifications and appointment reminders",        "expectedMessagingVolume": "10000",        "isTcrApplication": true,        "phoneNumberPrefix": "+1",        "destinationCountries": [          {            "id": "US",            "isMain": false          }        ],        "notes": null      }    },    "payment_details": {      "card_number": "4111111111111111",      "expiry": "09/27",      "cvc": "123",      "zip_code": "10001"    },    "sandbox": false  }'
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Sales Team",
    "email": "team@acme.com",
    "icon": "https://example.com/sales-icon.png",
    "description": "Sales department sender profile",
    "short_name": "SALES",
    "status": "incomplete",
    "created_at": "2026-03-11T21:50:50.1141567+00:00",
    "updated_at": "2026-03-11T21:50:50.1141728+00:00",
    "allow_contact_sharing": true,
    "allow_template_sharing": false,
    "inherit_contacts": true,
    "inherit_templates": true,
    "inherit_tcr_brand": false,
    "inherit_tcr_campaign": false,
    "billing_model": "profile",
    "sending_phone_number_profile_id": null,
    "sending_whatsapp_number_profile_id": null,
    "sending_phone_number": null,
    "whatsapp_phone_number": null,
    "allow_number_change_during_onboarding": null,
    "waba_id": "123456789012345",
    "billing_contact": {
      "name": "Acme Corp",
      "email": "billing@acmecorp.com",
      "phone": "+12025551234",
      "address": "123 Main Street, New York, NY 10001, US"
    },
    "brand": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tcr_brand_id": null,
      "status": null,
      "identity_status": null,
      "universal_ein": null,
      "csp_id": null,
      "submitted_to_tcr": false,
      "submitted_at": null,
      "is_inherited": false,
      "created_at": "2026-03-11T21:50:50.1144819+00:00",
      "updated_at": null,
      "contact": {
        "name": "John Smith",
        "business_name": "Acme Corp",
        "role": null,
        "phone": null,
        "email": "john@acmecorp.com",
        "phone_country_code": null
      },
      "business": {
        "legal_name": "Acme Corporation LLC",
        "tax_id": null,
        "tax_id_type": null,
        "entity_type": null,
        "street": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": "US",
        "url": null,
        "country_of_registration": null
      },
      "compliance": {
        "vertical": "PROFESSIONAL",
        "brand_relationship": "SMALL_ACCOUNT",
        "primary_use_case": null,
        "expected_messaging_volume": null,
        "is_tcr_application": true,
        "phone_number_prefix": null,
        "destination_countries": [
          {
            "id": "US",
            "isMain": false
          }
        ],
        "notes": null
      }
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.1147687+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_001",
    "message": "Request validation failed",
    "details": {
      "name": [
        "Profile name is required"
      ],
      "short_name": [
        "short_name must be 3–11 characters, contain only letters, numbers, and spaces, and include at least one letter"
      ],
      "payment_details.expiry": [
        "payment_details.expiry must be in MM/YY format (e.g. '09/27')"
      ]
    },
    "doc_url": "https://docs.sent.dm/errors/VALIDATION_001"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.1147845+00:00",
    "version": "v3"
  }
}
Empty
Empty
{
  "success": false,
  "data": null,
  "error": {
    "code": "RESOURCE_005",
    "message": "Organization not found",
    "details": null,
    "doc_url": "https://docs.sent.dm/errors/RESOURCE_005"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.114785+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_001",
    "message": "Organization does not have a WhatsApp Business Account configured. Complete WhatsApp Embedded Signup for your organization first, or provide direct credentials in the 'whatsapp_business_account' field.",
    "details": null,
    "doc_url": "https://docs.sent.dm/errors/VALIDATION_001"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.1147853+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_001",
    "message": "Failed to create profile. Please contact support with request ID: req_7X9zKp2jDw",
    "details": null,
    "doc_url": "https://docs.sent.dm/errors/INTERNAL_001"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.1147865+00:00",
    "version": "v3"
  }
}

Get profile by ID GET

Retrieves detailed information about a specific sender profile within an organization, including brand and KYC information if a brand has been configured.

Update profile settings PATCH

Updates a profile's configuration and settings. Requires admin role in the organization. Only provided fields will be updated (partial update). ## Brand Management Include the optional `brand` field to create or update the brand associated with this profile. The brand holds KYC and TCR compliance data (legal business info, contact details, messaging vertical). Once a brand has been submitted to TCR it cannot be modified. Setting `inherit_tcr_brand: true` and providing `brand` in the same request is not allowed. ## Payment Details When `billing_model` is `"profile"` or `"profile_and_organization"` you may include a `payment_details` object containing the card number, expiry (MM/YY), CVC, and billing ZIP code. Payment details are **never stored** on our servers and are forwarded directly to the payment processor. Providing `payment_details` when `billing_model` is `"organization"` is not allowed.