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={
"businessVerification": {
"businessProfileId": "664a1b2c3d4e5f6071829300",
"expectedIdentityRevision": 1,
"relationship": "account_business",
"confirmed": True,
},
"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",
"termsConditionsUrl": "https://acme.com/sms-terms",
"privacyPolicyUrl": "https://acme.com/privacy",
"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"
}
}
Number Requests (v2)
Create Number Request
Submit a complete request-owned identity and program for number provisioning.
POST
/
v2
/
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={
"businessVerification": {
"businessProfileId": "664a1b2c3d4e5f6071829300",
"expectedIdentityRevision": 1,
"relationship": "account_business",
"confirmed": True,
},
"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",
"termsConditionsUrl": "https://acme.com/sms-terms",
"privacyPolicyUrl": "https://acme.com/privacy",
"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
If saving succeeds but binding or submission fails, the error includes
GB VAT must contain
Identifier-type errors include
status: "pending" and enters the Trackly review queue. Poll Get Number Request to track it.
Supply an explicit nested
businessVerification confirmation for the matching business and its current revision. Bare businessProfileId is rejected. Current verification evidence must authorize this specific request. For onboarding while verification is pending, use the resumable draft flow.This is a live-key write. New submission requires a paid plan or approved billing bypass and a current API-key owner with a verified email. Sandbox keys can read number requests but cannot create them.
Send a unique
Idempotency-Key to retry this create safely. The first successful response, or an error containing a saved requestId, is cached for 24 hours. Repeating the same key and body replays that status and body; 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. US toll-free requests require both termsConditionsUrl and privacyPolicyUrl; 10DLC requires termsConditionsUrl.Business confirmation
object
required
Supply
businessProfileId, expectedIdentityRevision (integer, minimum 0 for a legacy profile), relationship (account_business or client_business), and confirmed: true. Fetch the current business and obtain customer confirmation before sending this object. See Confirm Business.requestId. Read that request, correct its fields or business confirmation as needed, and submit the same draft. Retrying one-shot creation with the original key continues replaying the cached error, even after verification or account eligibility changes. Validation errors before saving have no requestId and release the key for a corrected create.
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
Authorized representative email when it differs from the public support address in
contactEmail. Readiness reviews the representative and public support contacts in their separate roles.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 US toll-free and 10DLC.
string
required
Public opt-in page URL. Trackly captures it as carrier opt-in evidence.
string
HTTP(S) Terms and Conditions URL, up to 500 characters. Trackly validates its syntax but does not require its host to resolve publicly. Required for 10DLC.
string
HTTP(S) privacy policy URL, up to 500 characters. Required for US toll-free requests.
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 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={
"businessVerification": {
"businessProfileId": "664a1b2c3d4e5f6071829300",
"expectedIdentityRevision": 1,
"relationship": "account_business",
"confirmed": True,
},
"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",
"termsConditionsUrl": "https://acme.com/sms-terms",
"privacyPolicyUrl": "https://acme.com/privacy",
"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 | Use the nested confirmation object; the bare profile id is not accepted. |
| 400 | business_confirmation_required | Explicit business confirmation is missing or malformed. |
| 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 | websiteUrl or optInFormUrl is not publicly reachable, or termsConditionsUrl is not a valid HTTP(S) URL. |
| 400 | vertical_required | 10DLC is missing a valid vertical. |
| 400 | terms_conditions_url_required | 10DLC is missing a Terms and Conditions URL. |
| 400 | field_too_long | brandName or companyLegalName exceeds 255 characters. |
| 400 | messaging_type_invalid | messagingType is not a supported messaging use case. |
| 400 | invalid_field | A field value is invalid or exceeds its maximum length. |
| 403 | api_key_has_no_owner | The API key is not linked to a user. |
| 403 | paid_plan_required | Upgrade to a paid plan before submitting; a saved draft remains available by requestId. |
| 403 | email_verification_required | The current key owner must verify their email before submitting. |
| 409 | business_identity_changed | Reload the current business revision and obtain confirmation again. |
| 422 | Business verification error | The confirmed business is pending, expired, stale, unproven, or does not match the request. Follow the response code and message, then resume requestId. |
| 403 | sandbox_read_only | Sandbox keys cannot create number requests. |
| 422 | short_code_not_supported | phoneNumberType is short_code. Short code requests are not available through the API; contact support. |
| 422 | address_country_invalid | addressCountry is not a recognized or supported business country. |
| 422 | address_state_invalid | addressState is invalid for the address country. |
| 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. |
allowedIdentifierTypes when choices are available.
Next steps
Update Number Request
Correct request-owned identity while it is editable
Look Up Requirements
Discover non-US form and document requirements