---
title: "Create a new profile"
method: POST
path: "/v3/profiles"
tags: ["Profiles"]
---

# Create a new profile

`POST /v3/profiles`

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.

## Headers

- `Idempotency-Key` string
- `x-profile-id` string, uuid

## Request body

- SentDmServicesEndpointsCustomerAPIv3RequestsCreateProfileRequest — Request to create a new profile
  - `sandbox` boolean — Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution
  - `name` string, required — Profile name (required)
  - `icon` string, nullable — Profile icon URL (optional)
  - `description` string, nullable — Profile description (optional)
  - `short_name` string, nullable — Profile short name/abbreviation (optional). Must be 3–11 characters, contain only letters, numbers, and spaces, and include at least one letter. Example: "SALES", "Mkt 2", "Support1".
  - `allow_contact_sharing` boolean — Whether contacts are shared across profiles (default: false)
  - `allow_template_sharing` boolean — Whether templates are shared across profiles (default: false)
  - `inherit_contacts` boolean, nullable — Whether this profile inherits contacts from organization (default: true)
  - `inherit_templates` boolean, nullable — Whether this profile inherits templates from organization (default: true)
  - `inherit_tcr_brand` boolean, nullable — Whether this profile inherits TCR brand from organization (default: true)
  - `inherit_tcr_campaign` boolean, nullable — Whether this profile inherits TCR campaign from organization (default: true)
  - `billing_model` string, nullable — Billing model: profile, organization, or profile_and_organization (default: profile). - "organization": the organization's billing details are used; no profile-level billing info needed. - "profile": the profile is billed independently; billing_contact is required. - "profile_and_organization": the profile is billed first with the organization as fallback; billing_contact is required.
  - `billing_contact` SentDmServicesEndpointsCustomerAPIv3RequestsBillingContactInfo — Billing contact information for a profile. Required when billing_model is "profile" or "profile_and_organization".
    - `name` string, required — Full name of the billing contact or company (required)
    - `email` string, email, required — Email address where invoices will be sent (required)
    - `phone` string, nullable — Phone number for the billing contact (optional)
    - `address` string, nullable — Billing address (optional). Free-form text including street, city, state, postal code, and country.
  - `whatsapp_business_account` SentDmServicesEndpointsCustomerAPIv3RequestsWhatsappBusinessAccountCredentials — Direct WhatsApp Business Account credentials for a profile. Use this when the profile should have its own WhatsApp Business Account instead of inheriting from the organization. Credentials must be obtained from Meta Business Manager by creating a System User with whatsapp_business_messaging and whatsapp_business_management scopes.
    - `waba_id` string, required — WhatsApp Business Account ID from Meta Business Manager
    - `phone_number_id` string, nullable — Phone Number ID of an existing number already registered under this WABA in Meta Business Manager. Optional — when omitted, a number will be provisioned from our pool and registered in the WABA during the onboarding flow. When provided, the number must already exist in the WABA.
    - `access_token` string, required — System User access token with whatsapp_business_messaging and whatsapp_business_management permissions. This value is stored securely and never returned in API responses.
  - `brand` SentDmServicesEndpointsCustomerAPIv3RequestsBrandsBrandData — Brand and KYC data grouped into contact, business, and compliance sections
    - `contact` SentDmServicesEndpointsCustomerAPIv3RequestsBrandsBrandContactInfo, required — Contact information for brand KYC
      - `name` string, required — Primary contact name (required)
      - `businessName` string, nullable — Business/brand name
      - `role` string, nullable — Contact's role in the business
      - `phone` string, nullable — Contact phone number in E.164 format
      - `email` string, email, nullable — Contact email address
      - `phoneCountryCode` string, nullable — Contact phone country code (e.g., "1" for US)
    - `business` SentDmServicesEndpointsCustomerAPIv3RequestsBrandsBrandBusinessInfo — Business details and address for brand KYC
      - `legalName` string, nullable — Legal business name
      - `taxId` string, nullable — Tax ID/EIN number
      - `taxIdType` string, nullable — Type of tax ID (e.g., us_ein, ca_bn)
      - `entityType` 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'SOLE_PROPRIETOR' | 'GOVERNMENT'
      - `street` string, nullable — Street address
      - `city` string, nullable — City
      - `state` string, nullable — State/province code
      - `postalCode` string, nullable — Postal/ZIP code
      - `country` string, nullable — Country code (e.g., US, CA)
      - `url` string, uri, nullable — Business website URL
      - `countryOfRegistration` string, nullable — Country where the business is registered
    - `compliance` SentDmServicesEndpointsCustomerAPIv3RequestsBrandsBrandComplianceInfo, required — Compliance and TCR information for brand registration
      - `vertical` 'PROFESSIONAL' | 'REAL_ESTATE' | 'HEALTHCARE' | 'HUMAN_RESOURCES' | 'ENERGY' | 'ENTERTAINMENT' | 'RETAIL' | 'TRANSPORTATION' | 'AGRICULTURE' | 'INSURANCE' | 'POSTAL' | 'EDUCATION' | 'HOSPITALITY' | 'FINANCIAL' | 'POLITICAL' | 'GAMBLING' | 'LEGAL' | 'CONSTRUCTION' | 'NGO' | 'MANUFACTURING' | 'GOVERNMENT' | 'TECHNOLOGY' | 'COMMUNICATION', required
      - `brandRelationship` 'BASIC_ACCOUNT' | 'MEDIUM_ACCOUNT' | 'LARGE_ACCOUNT' | 'SMALL_ACCOUNT' | 'KEY_ACCOUNT', required
      - `primaryUseCase` string, nullable — Primary messaging use case description
      - `expectedMessagingVolume` string, nullable — Expected daily messaging volume
      - `isTcrApplication` boolean, nullable — Whether this is a TCR (Campaign Registry) application
      - `phoneNumberPrefix` string, nullable — Phone number prefix for messaging (e.g., "+1")
      - `destinationCountries` SentDmServicesCommonEntitiesDestinationCountry[], nullable — List of destination countries for messaging
        - `id` string
        - `isMain` boolean
      - `notes` string, nullable — Additional notes about the business or use case
  - `payment_details` SentDmServicesEndpointsCustomerAPIv3RequestsPaymentDetails — Payment card details for a profile. Accepted when billing_model is "profile" or "profile_and_organization". These details are not stored on our servers and will be forwarded to the payment processor.
    - `card_number` string, required — Card number (digits only, 13–19 characters)
    - `expiry` string, required — Card expiry date in MM/YY format (e.g. "09/27")
    - `cvc` string, required — Card security code (3–4 digits)
    - `zip_code` string, required — Billing ZIP / postal code associated with the card

## Response `201`

Profile created successfully

- SentDmServicesEndpointsCustomerAPIv3ResponsesApiResponseOfProfileDetailResponse — Standard API response envelope for all v3 endpoints
  - `success` boolean — Indicates whether the request was successful
  - `data` SentDmServicesEndpointsCustomerAPIv3ResponsesProfileDetailResponse — Detailed profile response for v3 API
    - `id` string, uuid — Profile unique identifier
    - `organization_id` string, uuid, nullable — Parent organization ID
    - `name` string — Profile name
    - `email` string, nullable — Profile email (inherited from organization)
    - `icon` string, nullable — Profile icon URL
    - `description` string, nullable — Profile description
    - `short_name` string, nullable — Profile short name/abbreviation. 3–11 characters: letters, numbers, and spaces only, with at least one letter.
    - `status` string — Profile setup status: incomplete, pending_review, approved, rejected
    - `created_at` string, date-time — When the profile was created
    - `updated_at` string, date-time, nullable — When the profile was last updated
    - `allow_contact_sharing` boolean — Whether contacts are shared across profiles in the organization
    - `allow_template_sharing` boolean — Whether templates are shared across profiles in the organization
    - `inherit_contacts` boolean — Whether this profile inherits contacts from the organization
    - `inherit_templates` boolean — Whether this profile inherits templates from the organization
    - `inherit_tcr_brand` boolean — Whether this profile inherits TCR brand from the organization
    - `inherit_tcr_campaign` boolean — Whether this profile inherits TCR campaign from the organization
    - `billing_model` string — Billing model: profile, organization, or profile_and_organization
    - `sending_phone_number_profile_id` string, uuid, nullable — Reference to another profile for SMS/Telnyx configuration
    - `sending_whatsapp_number_profile_id` string, uuid, nullable — Reference to another profile for WhatsApp configuration
    - `sending_phone_number` string, nullable — Direct SMS phone number
    - `whatsapp_phone_number` string, nullable — Direct WhatsApp phone number
    - `allow_number_change_during_onboarding` boolean, nullable — Whether number changes are allowed during onboarding
    - `waba_id` string, nullable — WhatsApp Business Account ID associated with this profile. Present whether the WABA is inherited from the organization or configured directly.
    - `billing_contact` SentDmServicesEndpointsCustomerAPIv3ResponsesBillingContactResponse — Billing contact info returned in profile responses
      - `name` string, nullable
      - `email` string, nullable
      - `phone` string, nullable
      - `address` string, nullable
    - `brand` SentDmServicesEndpointsCustomerAPIv3ResponsesBrandsBrandWithKycResponse — Brand response with nested contact, business, and compliance sections — mirrors the request structure.
      - `id` string, uuid — Unique identifier for the brand
      - `tcr_brand_id` string, nullable — TCR brand ID (populated after TCR submission)
      - `status` 'ACTIVE' | 'INACTIVE' | 'SUSPENDED'
      - `identity_status` 'SELF_DECLARED' | 'UNVERIFIED' | 'VERIFIED' | 'VETTED_VERIFIED'
      - `universal_ein` string, nullable — Universal EIN from TCR
      - `csp_id` string, nullable — CSP (Campaign Service Provider) ID
      - `submitted_to_tcr` boolean — Whether this brand has been submitted to TCR
      - `submitted_at` string, date-time, nullable — When the brand was submitted to TCR
      - `is_inherited` boolean — Whether this brand is inherited from the parent organization
      - `created_at` string, date-time — When the brand was created
      - `updated_at` string, date-time, nullable — When the brand was last updated
      - `contact` SentDmServicesEndpointsCustomerAPIv3ResponsesBrandsBrandContactResponse
        - `name` string — Primary contact name
        - `business_name` string, nullable — Business/brand name
        - `role` string, nullable — Contact's role in the business
        - `phone` string, nullable — Contact phone number in E.164 format
        - `email` string, nullable — Contact email address
        - `phone_country_code` string, nullable — Contact phone country code (e.g., "1" for US)
      - `business` SentDmServicesEndpointsCustomerAPIv3ResponsesBrandsBrandBusinessResponse
        - `legal_name` string, nullable — Legal business name
        - `tax_id` string, nullable — Tax ID/EIN number
        - `tax_id_type` string, nullable — Type of tax ID (e.g., us_ein, ca_bn)
        - `entity_type` string, nullable — Business entity type
        - `street` string, nullable — Street address
        - `city` string, nullable — City
        - `state` string, nullable — State/province code
        - `postal_code` string, nullable — Postal/ZIP code
        - `country` string, nullable — Country code (e.g., US, CA)
        - `url` string, nullable — Business website URL
        - `country_of_registration` string, nullable — Country where the business is registered
      - `compliance` SentDmServicesEndpointsCustomerAPIv3ResponsesBrandsBrandComplianceResponse
        - `vertical` 'PROFESSIONAL' | 'REAL_ESTATE' | 'HEALTHCARE' | 'HUMAN_RESOURCES' | 'ENERGY' | 'ENTERTAINMENT' | 'RETAIL' | 'TRANSPORTATION' | 'AGRICULTURE' | 'INSURANCE' | 'POSTAL' | 'EDUCATION' | 'HOSPITALITY' | 'FINANCIAL' | 'POLITICAL' | 'GAMBLING' | 'LEGAL' | 'CONSTRUCTION' | 'NGO' | 'MANUFACTURING' | 'GOVERNMENT' | 'TECHNOLOGY' | 'COMMUNICATION'
        - `brand_relationship` 'BASIC_ACCOUNT' | 'MEDIUM_ACCOUNT' | 'LARGE_ACCOUNT' | 'SMALL_ACCOUNT' | 'KEY_ACCOUNT'
        - `primary_use_case` string, nullable — Primary messaging use case description
        - `expected_messaging_volume` string, nullable — Expected daily messaging volume
        - `is_tcr_application` boolean — Whether this is a TCR (Campaign Registry) application
        - `phone_number_prefix` string, nullable — Phone number prefix for messaging (e.g., "+1")
        - `destination_countries` SentDmServicesCommonEntitiesDestinationCountry[] — List of destination countries for messaging
          - `id` string
          - `isMain` boolean
        - `notes` string, nullable — Additional notes about the business or use case
  - `error` SentDmServicesEndpointsCustomerAPIv3ResponsesApiError — Error information
    - `code` string — Machine-readable error code (e.g., "RESOURCE_001")
    - `message` string — Human-readable error message
    - `details` object, nullable — Additional validation error details (field-level errors)
    - `doc_url` string, nullable — URL to documentation about this error
  - `meta` SentDmServicesEndpointsCustomerAPIv3ResponsesApiMeta — Request and response metadata
    - `request_id` string — Unique identifier for this request (for tracing and support)
    - `timestamp` string, date-time — Server timestamp when the response was generated
    - `version` string — API version used for this request

## Other responses

- `400` — Invalid request parameters
- `401` — Unauthorized - Invalid API credentials
- `403` — Forbidden - User does not have admin access to this organization
- `404` — Organization not found
- `422` — Organization has no WABA configured and no direct credentials provided
- `500` — Internal server error

---

[API](https://skmtc.net/sentdm/apis/sent-dm-api-v3.md) · [All operations](https://skmtc.net/sentdm/apis/sent-dm-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sentdm/sent-dm-api-v3/versions/c451eca46f1b/schema)