import requests
response = requests.patch(
"https://api.tracklysms.com/api/v2/number-requests/665f0a1b2c3d4e5f60718293",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Idempotency-Key": "number-request-update-665f0a1b",
},
json={
"addressCountry": "GB",
"addressState": "",
"taxId": "GB421084435",
},
)
{
"request": {
"id": "665f0a1b2c3d4e5f60718293",
"addressCountry": "GB",
"identifierType": "vat",
"targetCountries": ["US"],
"status": "pending",
"provisioningStatus": "failed",
"updatedAt": "2026-08-03T22:15:00"
}
}
Number Requests (v2)
Update Number Request
Update request-owned identity and program fields while provisioning is editable.
PATCH
/
v2
/
number-requests
/
{request_id}
import requests
response = requests.patch(
"https://api.tracklysms.com/api/v2/number-requests/665f0a1b2c3d4e5f60718293",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Idempotency-Key": "number-request-update-665f0a1b",
},
json={
"addressCountry": "GB",
"addressState": "",
"taxId": "GB421084435",
},
)
{
"request": {
"id": "665f0a1b2c3d4e5f60718293",
"addressCountry": "GB",
"identifierType": "vat",
"targetCountries": ["US"],
"status": "pending",
"provisioningStatus": "failed",
"updatedAt": "2026-08-03T22:15:00"
}
}
Updates an account-owned number request before provider identity is locked. Drafts accept partial fields and remain inert; required submission checks run when the draft is submitted. For a submitted request, the server merges supplied fields with the stored request and validates the complete result. Editing correction details does not require current verification, but submitting them to the provider does.
Identifier errors include
Carrier identity cannot be changed once brand registration has started or completed. Readiness corrections use the limited fields below and preserve the business identity, verification, request ID, and existing provider resources. Do not reset or replace a request to resolve a readiness finding.
phoneNumberType is immutable after creation. targetCountries can change only before a Resource Request exists. Changing it before that point clears stale international form values, documents, feedback, and status.Changing
addressCountry without identifierType clears the old type. A single-option country resolves automatically; AU, CA, FR, and ES require a new explicit country-scoped type.Send an
Idempotency-Key when retrying an update. The key is bound to this concrete request path and payload: an exact retry replays, while reuse for another request id returns 409 idempotency_conflict. See Idempotency.Path parameters
string
required
Number request id.
Body
Readiness corrections
Read registration readiness first. WhencanCorrect is true, an inactive ordinary request can accept changed values for promotionSummary, exampleSmsMessage, messagingType, contactEmail, contactPhone, privacyPolicyUrl, termsConditionsUrl, and optInFormUrl. Send only the fields being corrected. This path supports eligible pending, under_review, approved, and rejected requests as well as drafts; active provider operations remain guarded.
Saving does not reset status or submit the correction to a carrier. Read back the same request and recheck readiness before continuing. Identity changes remain locked, and agent-prepared requests require their owner revision flow in Trackly. A 409 requires readback and reconciliation of the existing request.
For this correction path, summaries are limited to 1,000 characters, example messages to 4,000, support email to 255, support phone to 20, and each URL to 500. Correction URLs must pass the server’s public HTTP(S) URL validation.
Other editable requests
The body accepts the request-owned fields from Create Number Request, including:brandName,companyLegalName,taxId, andidentifierType;- business address and carrier contacts;
websiteUrl,optInFormUrl,termsConditionsUrl, andprivacyPolicyUrl;targetCountries, messaging program fields, and volume.
businessProfileId nor businessVerification is a general PATCH field. Identity edits can invalidate existing confirmation; check the returned businessVerification summary. taxId remains write-only in the response.
termsConditionsUrl is syntax-checked as an HTTP(S) URL but does not need a publicly resolvable host; websiteUrl and optInFormUrl must remain publicly reachable.
Example
import requests
response = requests.patch(
"https://api.tracklysms.com/api/v2/number-requests/665f0a1b2c3d4e5f60718293",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Idempotency-Key": "number-request-update-665f0a1b",
},
json={
"addressCountry": "GB",
"addressState": "",
"taxId": "GB421084435",
},
)
{
"request": {
"id": "665f0a1b2c3d4e5f60718293",
"addressCountry": "GB",
"identifierType": "vat",
"targetCountries": ["US"],
"status": "pending",
"provisioningStatus": "failed",
"updatedAt": "2026-08-03T22:15:00"
}
}
Error codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | business_profile_not_allowed | Confirm the business through the dedicated binding endpoint. |
| 400 | target_countries_invalid | The merged request does not contain exactly one target. |
| 400 | field_too_long | brandName or companyLegalName exceeds 255 characters. |
| 400 | messaging_type_invalid | messagingType is not a supported messaging use case. |
| 400 | url_not_allowed | websiteUrl or optInFormUrl is not publicly reachable, or termsConditionsUrl is not a valid HTTP(S) URL. |
| 400 | invalid_field | A field value is invalid or exceeds its maximum length. |
| 400 | invalid_correction | The readiness correction is empty, contains an invalid value, or exceeds a correction field limit. |
| 409 | agent_review_required | An agent-prepared draft requires owner review in Trackly. |
| 403 | sandbox_read_only | A sandbox key attempted an update. |
| 404 | not_found | The request does not belong to the API-key account. |
| 409 | carrier_identity_locked | Provider identity is locked, or an inactive readiness correction includes fields outside its allowed set. Read the current request and use its authorized correction path. |
| 409 | request_not_editable | Provisioning is active. |
| 409 | number_request_changed | The request changed during the correction. Read back the same request before deciding what to retry. |
| 409 | phone_number_type_immutable | phoneNumberType changed. |
| 409 | acquisition_target_locked | A Resource Request already exists for the stored target. |
| 409 | acquisition_correction_not_allowed | A Resource Request exists but is not in a correctable provider state. |
| 422 | validation_failed | The merged request is missing a required field. |
| 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. |
allowedIdentifierTypes when choices are available.
Next steps
Get Number Request
Verify the persisted request
Correct Resource Request
Return requested provider changes on the same id