> ## 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 Number Request

> Submit a complete request-owned identity and program for number provisioning.

Creates a number request with `status: "pending"` and enters the Trackly review queue. Poll [Get Number Request](/api-reference/v2/number-requests/get-request) to track it.

<Warning>
  The account must already have a verified business. Verification is an account-level gate only. This endpoint does not select, create, update, or copy data from a Business Profile, and `businessProfileId` is rejected.
</Warning>

<Note>
  This is a live-key write. Sandbox keys can read number requests but cannot create them.
</Note>

<Note>
  Send a unique `Idempotency-Key` to retry this create safely. Repeating the same key with the same body replays the first successful response; changing the body returns `409 idempotency_conflict`. See [Idempotency](/api-reference/v2/idempotency).
</Note>

<Note>
  The API uses the customer-hosted `optInFormUrl` as carrier evidence and does not create a white-label opt-in site. A 10DLC request also requires `termsConditionsUrl`.
</Note>

## Identity

<ParamField body="brandName" type="string" required>
  Brand name.
</ParamField>

<ParamField body="companyLegalName" type="string" required>
  Registered legal entity name for this number request.
</ParamField>

<ParamField body="taxId" type="string" required>
  Carrier registration identifier selected by `addressCountry`. This value is write-only and is not returned by list, get, or create responses.
</ParamField>

<ParamField body="identifierType" type="string">
  Carrier identifier type. Omit it for a country with one option; Trackly stores the only valid type. It is required for AU, CA, FR, and ES and must be one of the country choices below.
</ParamField>

<ParamField body="businessContactFirstName" type="string" required>
  Authorized carrier contact first name.
</ParamField>

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

<ParamField body="industry" type="string">
  Business industry.
</ParamField>

## Address and contact

<ParamField body="addressStreet" type="string" required>
  Street address owned by this request.
</ParamField>

<ParamField body="addressCity" type="string" required>
  City.
</ParamField>

<ParamField body="addressState" type="string">
  State or province. Required when `addressCountry` is `US` or `CA`.
</ParamField>

<ParamField body="addressPostalCode" type="string" required>
  Postal or ZIP code.
</ParamField>

<ParamField body="addressCountry" type="string" required>
  ISO 3166-1 alpha-2 business address country. This field selects the carrier identifier type; it does not select the number country.
</ParamField>

<ParamField body="contactEmail" type="string" required>
  Carrier support email. Its domain must match the `websiteUrl` domain.
</ParamField>

<ParamField body="contactPhone" type="string">
  Carrier support phone.
</ParamField>

<ParamField body="websiteUrl" type="string" required>
  Public business website URL.
</ParamField>

## Number and program

<ParamField body="listName" type="string" required>
  Sending list name.
</ParamField>

<ParamField body="phoneNumberType" type="string" optional default="toll_free">
  `toll_free` or `10dlc`. Short codes are not available through public V2.
</ParamField>

<ParamField body="targetCountries" type="array" required>
  Exactly one ISO 3166-1 alpha-2 number country, such as `["US"]` or `["CA"]`. A US target uses USA sender registration. CA and other non-US targets use requirements-first number acquisition. 10DLC must target US.
</ParamField>

<ParamField body="messagingType" type="string" optional default="MIXED">
  Messaging use case, such as `GENERAL_MARKETING`, `TWO_FA`, or `MIXED`.
</ParamField>

<ParamField body="vertical" type="string">
  TCR business vertical. Required for 10DLC.
</ParamField>

<ParamField body="optInFormUrl" type="string" required>
  Public opt-in page URL. Trackly captures it as carrier opt-in evidence.
</ParamField>

<ParamField body="termsConditionsUrl" type="string">
  Public Terms and Conditions URL. Required for 10DLC.
</ParamField>

<ParamField body="promotionSummary" type="string">
  Messaging program summary.
</ParamField>

<ParamField body="exampleSmsMessage" type="string">
  Example message.
</ParamField>

<ParamField body="businessDescription" type="string">
  Business description.
</ParamField>

<ParamField body="estimatedMonthlyVolume" type="string">
  Estimated monthly segment volume.
</ParamField>

## Identifier types

| `addressCountry`           | Allowed `identifierType`          |
| -------------------------- | --------------------------------- |
| US                         | `ein`                             |
| GB, IE, NL                 | `vat`                             |
| DE                         | `ust_idnr`                        |
| CH                         | `uid`                             |
| NZ                         | `nzbn`                            |
| AU                         | `abn`, `acn`                      |
| CA                         | `cbn`, `neq`, `provincial_number` |
| FR                         | `siren`, `siret`                  |
| ES                         | `cif`, `nif`                      |
| Other two-letter countries | `registration_number`             |

GB VAT must contain `GB` followed by nine digits. For example, `GB421084435` is accepted; a bare company registry number is not. The `registration_number` fallback is bounded local validation and does not guarantee that every country and identifier is accepted by the carrier.

## International requirements

Before creating a CA or other non-US request, call [Look Up International Requirements](/api-reference/v2/number-requests/lookup-requirements). After creation, use [Manage International Requirements](/api-reference/v2/number-requests/update-requirements) to save provider form values and request-scoped documents.

## Example

<RequestExample>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tracklysms.com/api/v2/number-requests",
      headers={
          "X-Api-Key": "trk_your_api_key_here",
          "Idempotency-Key": "number-request-create-665f0a1b",
      },
      json={
          "brandName": "Acme Co",
          "companyLegalName": "Acme Incorporated",
          "listName": "Acme Alerts",
          "phoneNumberType": "toll_free",
          "messagingType": "GENERAL_MARKETING",
          "targetCountries": ["US"],
          "contactEmail": "support@acme.com",
          "websiteUrl": "https://acme.com",
          "optInFormUrl": "https://acme.com/sms-optin",
          "taxId": "12-3456789",
          "businessContactFirstName": "Jane",
          "businessContactLastName": "Doe",
          "addressStreet": "1 Main St",
          "addressCity": "Wilmington",
          "addressState": "DE",
          "addressPostalCode": "19801",
          "addressCountry": "US",
      },
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 201 — Created theme={null}
  {
    "request": {
      "id": "665f0a1b2c3d4e5f60718293",
      "brandName": "Acme Co",
      "companyLegalName": "Acme Incorporated",
      "listName": "Acme Alerts",
      "phoneNumberType": "toll_free",
      "targetCountries": ["US"],
      "addressCountry": "US",
      "identifierType": "ein",
      "status": "pending",
      "provisioningStatus": "not_started",
      "internationalAcquisitionStatus": null,
      "createdAt": "2026-08-03T22:00:00"
    }
  }
  ```
</ResponseExample>

## Error codes

| HTTP | Code                             | Meaning                                                                                                   |
| ---- | -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 400  | `business_profile_not_allowed`   | Remove `businessProfileId` and send the complete identity inline.                                         |
| 400  | `target_countries_invalid`       | `targetCountries` does not contain exactly one item.                                                      |
| 400  | `target_country_invalid`         | Target code is malformed or 10DLC does not target US.                                                     |
| 400  | `contact_email_brand_mismatch`   | Contact email and website domains do not match.                                                           |
| 400  | `url_not_allowed`                | A carrier-facing URL is not an allowed public URL.                                                        |
| 400  | `vertical_required`              | 10DLC is missing a valid vertical.                                                                        |
| 400  | `terms_conditions_url_required`  | 10DLC is missing a Terms and Conditions URL.                                                              |
| 403  | `business_verification_required` | A live account has no active verified business. Complete business verification before creating a request. |
| 403  | `sandbox_read_only`              | Sandbox keys cannot create number requests. This check occurs before the business-verification gate.      |
| 422  | `tax_id_invalid`                 | Carrier identifier format is invalid for the address country.                                             |
| 422  | `identifier_type_required`       | A multi-option country needs an explicit type.                                                            |
| 422  | `identifier_type_invalid`        | The type is not valid for the address country.                                                            |
| 422  | `validation_failed`              | Required inline request fields are missing.                                                               |
| 422  | `unsupported_target_country`     | The target is outside provisioning coverage.                                                              |

Identifier-type errors include `allowedIdentifierTypes` when choices are available.

## Next steps

<CardGroup cols={2}>
  <Card title="Update Number Request" icon="pen" href="/api-reference/v2/number-requests/update-request">
    Correct request-owned identity while it is editable
  </Card>

  <Card title="Look Up Requirements" icon="list-check" href="/api-reference/v2/number-requests/lookup-requirements">
    Discover non-US form and document requirements
  </Card>
</CardGroup>