Create Number Request

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",
    },
)

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

POST

number-requests

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",
    },
)

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

Creates a number request with status: "pending" and enters the Trackly review queue. Poll Get Number Request to track it.

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.

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

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.

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.

Identity

string

required

Brand name.

string

required

Registered legal entity name for this number request.

string

required

Carrier registration identifier selected by addressCountry. This value is write-only and is not returned by list, get, or create responses.

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.

string

required

Authorized carrier contact first name.

string

required

Authorized carrier contact last name.

string

Business industry.

Address and contact

string

required

Street address owned by this request.

string

required

City.

string

State or province. Required when addressCountry is US or CA.

string

required

Postal or ZIP code.

string

required

ISO 3166-1 alpha-2 business address country. This field selects the carrier identifier type; it does not select the number country.

string

required

Carrier support email. Its domain must match the websiteUrl domain.

string

Carrier support phone.

string

required

Public business website URL.

Number and program

string

required

Sending list name.

string

default:"toll_free"

toll_free or 10dlc. Short codes are not available through public V2.

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.

string

default:"MIXED"

Messaging use case, such as GENERAL_MARKETING, TWO_FA, or MIXED.

string

TCR business vertical. Required for 10DLC.

string

required

Public opt-in page URL. Trackly captures it as carrier opt-in evidence.

string

Public Terms and Conditions URL. Required for 10DLC.

string

Messaging program summary.

string

Example message.

string

Business description.

string

Estimated monthly segment volume.

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. After creation, use Manage International Requirements to save provider form values and request-scoped documents.

Example

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",
    },
)

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

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.

API Reference

V2 API Reference

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Profiles (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

API Reference (v1 - Deprecated)

Create Number Request

Identity

Address and contact

Number and program

Identifier types

International requirements

Example

Error codes

Next steps

Update Number Request

Look Up Requirements

​Identity

​Address and contact

​Number and program

​Identifier types

​International requirements

​Example

​Error codes

​Next steps

Update Number Request

Look Up Requirements

Identity

Address and contact

Number and program

Identifier types

International requirements

Example

Error codes

Next steps