> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Business Profile

> Create a business identity profile; KYB verification starts automatically once the identity is complete.

Creates a business profile on your account. Only `name` is required — you can create a draft and fill it in later. When the profile carries a **complete identity** (`companyLegalName`, `taxId`, `addressCountry`, `businessContactFirstName`, `businessContactLastName`), KYB verification **starts automatically**.

Submission is asynchronous, so this response still reports `verificationStatus: "unverified"`; it moves to `pending` shortly after, once the submission is accepted. Poll [Get Business Profile](/api-reference/v2/business-profiles/get-profile) or subscribe to the `business_profile.*` webhooks rather than reading the outcome off the create response.

<Note>
  Requires a **live** key. This endpoint is [idempotent](/api-reference/v2/idempotency): send an `Idempotency-Key` header to make retries safe.
</Note>

## Body Parameters

<ParamField body="name" type="string" required>
  Profile label (distinct from the brand name — an account can hold several profiles). Max 100 characters.
</ParamField>

<ParamField body="companyLegalName" type="string">
  Registered legal entity name, as it appears on IRS/registry records. For US TIN match, the sanitized name must be ≤ 40 characters.
</ParamField>

<ParamField body="taxId" type="string">
  EIN / TIN. Validated against `addressCountry`'s format; stored in its canonical form.
</ParamField>

<ParamField body="identifierType" type="string">
  Type of value in `taxId` (e.g. `ein`, `cbn`, `neq`, `provincial_number`, `registration_number`). Auto-defaulted for countries with exactly one legal value; **CA requires an explicit choice.**
</ParamField>

<ParamField body="addressCountry" type="string">
  ISO 3166-1 country (alpha-2, alpha-3, or full name). Must be a [supported jurisdiction](/api-reference/v2/business-profiles/validate-profile).
</ParamField>

<ParamField body="businessContactFirstName" type="string">
  Authorized contact first name (required by the carrier registry at verification).
</ParamField>

<ParamField body="businessContactLastName" type="string">
  Authorized contact last name.
</ParamField>

<ParamField body="addressStreet" type="string">Street.</ParamField>
<ParamField body="addressCity" type="string">City.</ParamField>
<ParamField body="addressState" type="string">State/region (coerced to a 2-letter code where applicable).</ParamField>
<ParamField body="addressPostalCode" type="string">Postal code.</ParamField>
<ParamField body="brandName" type="string">Brand name.</ParamField>
<ParamField body="websiteUrl" type="string">Business website URL.</ParamField>
<ParamField body="contactEmail" type="string">Business contact email.</ParamField>
<ParamField body="industry" type="string">Industry / vertical.</ParamField>

## Response Fields

<ResponseField name="businessProfile" type="object">
  The created profile (see [Get Business Profile](/api-reference/v2/business-profiles/get-profile)). `verificationStatus` is `unverified` in this response even when KYB was auto-submitted — the move to `pending` happens asynchronously. `taxIdLast4` is returned in place of the full tax id.
</ResponseField>

## Examples

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST "https://api.tracklysms.com/api/v2/business-profiles" \
      -H "X-Api-Key: trk_your_api_key_here" \
      -H "Idempotency-Key: create-acme-profile-1" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Acme Retail Profile",
        "companyLegalName": "Acme Incorporated",
        "taxId": "12-3456789",
        "addressCountry": "US",
        "businessContactFirstName": "Jane",
        "businessContactLastName": "Doe"
      }'
    ```

    ```python Python theme={null}
    import requests

    resp = requests.post(
        "https://api.tracklysms.com/api/v2/business-profiles",
        headers={"X-Api-Key": "trk_your_api_key_here", "Idempotency-Key": "create-acme-profile-1"},
        json={
            "name": "Acme Retail Profile",
            "companyLegalName": "Acme Incorporated",
            "taxId": "12-3456789",
            "addressCountry": "US",
            "businessContactFirstName": "Jane",
            "businessContactLastName": "Doe",
        },
    )
    print(resp.json()["businessProfile"]["verificationStatus"])
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 201 — Created theme={null}
  {
    "businessProfile": {
      "id": "664a1b2c3d4e5f6071829300",
      "name": "Acme Retail Profile",
      "companyLegalName": "Acme Incorporated",
      "taxIdLast4": "6789",
      "addressCountry": "US",
      "verificationStatus": "unverified",
      "supportingDocumentCount": 0,
      "createdAt": "2026-07-26T12:00:00Z"
    }
  }
  ```

  ```json 422 — Validation error theme={null}
  {
    "error": "validation_failed",
    "fields": [
      { "field": "taxId", "code": "compliance_tax_id_format", "message": "taxId format is invalid for US" }
    ]
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code                         | Description                                                                                                |
| ----------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 400         | `missing_name`                     | `name` is required.                                                                                        |
| 403         | `sandbox_read_only`                | Sandbox keys cannot create profiles — use a live key.                                                      |
| 403         | `account_locked` / `daily_cap_hit` | A rejected/locked profile on the account, or the daily verification cap, blocks new profiles.              |
| 422         | `validation_failed`                | One or more identity fields are invalid — see `fields`. **For CA profiles, `identifierType` is required.** |

## Next Steps

<CardGroup cols={2}>
  <Card title="Validate first" icon="list-check" href="/api-reference/v2/business-profiles/validate-profile">
    Dry-run field validation before creating.
  </Card>

  <Card title="Submission history" icon="clock-rotate-left" href="/api-reference/v2/business-profiles/list-submissions">
    Track the KYB verdict.
  </Card>
</CardGroup>