import base64
import requests
document_data = base64.b64encode(open("registration.pdf", "rb").read()).decode()
response = requests.patch(
"https://api.tracklysms.com/api/v2/number-requests/665f0a1b2c3d4e5f60718293/international-requirements",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Idempotency-Key": "number-request-requirements-665f0a1b",
},
json={
"internationalAcquisitionFormData": {
"companyName": "Acme Incorporated"
},
"internationalAcquisitionDocuments": [
{
"requirementKey": "proofOfBusinessRegistration",
"filename": "registration.pdf",
"contentType": "application/pdf",
"data": document_data,
}
],
},
)
{
"internationalAcquisition": {
"status": "UPDATE_REQUESTED",
"requirements": [
{
"key": "companyName",
"type": "text",
"required": true
},
{
"key": "proofOfBusinessRegistration",
"type": "document",
"required": true
}
],
"formData": {
"companyName": "Acme Incorporated"
},
"documents": [
{
"requirementKey": "proofOfBusinessRegistration",
"filename": "registration.pdf",
"contentType": "application/pdf",
"size": 48192,
"uploadedAt": "2026-08-03T22:10:00"
}
],
"feedback": {}
}
}
Number Requests (v2)
Update International Requirements
Save request-owned form values and provisioning documents.
PATCH
/
v2
/
number-requests
/
{request_id}
/
international-requirements
import base64
import requests
document_data = base64.b64encode(open("registration.pdf", "rb").read()).decode()
response = requests.patch(
"https://api.tracklysms.com/api/v2/number-requests/665f0a1b2c3d4e5f60718293/international-requirements",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Idempotency-Key": "number-request-requirements-665f0a1b",
},
json={
"internationalAcquisitionFormData": {
"companyName": "Acme Incorporated"
},
"internationalAcquisitionDocuments": [
{
"requirementKey": "proofOfBusinessRegistration",
"filename": "registration.pdf",
"contentType": "application/pdf",
"data": document_data,
}
],
},
)
{
"internationalAcquisition": {
"status": "UPDATE_REQUESTED",
"requirements": [
{
"key": "companyName",
"type": "text",
"required": true
},
{
"key": "proofOfBusinessRegistration",
"type": "document",
"required": true
}
],
"formData": {
"companyName": "Acme Incorporated"
},
"documents": [
{
"requirementKey": "proofOfBusinessRegistration",
"filename": "registration.pdf",
"contentType": "application/pdf",
"size": 48192,
"uploadedAt": "2026-08-03T22:10:00"
}
],
"feedback": {}
}
}
Persists dynamic provider answers and request-scoped documents for one account-owned number request. Use only keys returned by Get International Requirements.
Only these three fields are accepted.
Business Profile documents cannot be referenced or reused. Upload each provisioning document to this NumberRequest.
This endpoint saves local request data. When the provider status asks for changes, call Correct Resource Request to PATCH the same provider request.
Send an
Idempotency-Key when retrying saved answers or uploads. The key is bound to this concrete request path and payload; use a new key after changing either. See Idempotency.Path parameters
string
required
Number request id.
Body
object
Complete form-value object keyed by non-document requirement key. When supplied, it replaces the saved form object. Accepts at most 50 keys; more returns
400 form_data_invalid. Values must be scalar and are stored as bounded strings.array
New or replacement request-owned documents. Each item contains:
requirementKey: exact document requirement key;filename: display filename;contentType:application/pdf,image/jpeg,image/png, orimage/webp;data: base64-encoded file bytes.
array
Requirement keys whose stored documents should be removed.
businessProfileDocumentId is rejected.
Example
import base64
import requests
document_data = base64.b64encode(open("registration.pdf", "rb").read()).decode()
response = requests.patch(
"https://api.tracklysms.com/api/v2/number-requests/665f0a1b2c3d4e5f60718293/international-requirements",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Idempotency-Key": "number-request-requirements-665f0a1b",
},
json={
"internationalAcquisitionFormData": {
"companyName": "Acme Incorporated"
},
"internationalAcquisitionDocuments": [
{
"requirementKey": "proofOfBusinessRegistration",
"filename": "registration.pdf",
"contentType": "application/pdf",
"data": document_data,
}
],
},
)
{
"internationalAcquisition": {
"status": "UPDATE_REQUESTED",
"requirements": [
{
"key": "companyName",
"type": "text",
"required": true
},
{
"key": "proofOfBusinessRegistration",
"type": "document",
"required": true
}
],
"formData": {
"companyName": "Acme Incorporated"
},
"documents": [
{
"requirementKey": "proofOfBusinessRegistration",
"filename": "registration.pdf",
"contentType": "application/pdf",
"size": 48192,
"uploadedAt": "2026-08-03T22:10:00"
}
],
"feedback": {}
}
}
Error codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | unsupported_field | Body contains a field outside the three acquisition fields. |
| 400 | carrier_identifier_not_editable | A carrier-identifier requirement was supplied directly. Update request-owned taxId and identifierType through Update Number Request. |
| 400 | requirement_key_invalid | Form or document key is not in the live requirement schema. |
| 400 | business_profile_document_not_allowed | A Business Profile document id was supplied. |
| 400 | document_data_invalid | Document data is missing or invalid base64. |
| 400 | document_size_invalid | One document is empty or exceeds 5 MB. |
| 400 | document_type_invalid | Content type is unsupported. |
| 400 | document_type_mismatch | Declared type does not match file bytes. |
| 400 | attachments_too_large | Aggregate request documents exceed 15 MB. |
| 400 | too_many_documents | More than 10 document keys would be stored. |
| 400 | form_data_invalid | internationalAcquisitionFormData is not an object or exceeds 50 keys. |
| 400 | form_value_invalid | A form value is not scalar. |
| 400 | removed_document_keys_invalid | internationalAcquisitionDocumentRemovedKeys is not a list, or contains more than 10 keys. |
| 400 | documents_invalid | internationalAcquisitionDocuments is not a list. |
| 400 | invalid_field | A field value is invalid or exceeds its maximum length. |
| 403 | sandbox_read_only | A sandbox key attempted a write. |
| 404 | not_found | Request does not belong to the API-key account. |
| 409 | acquisition_not_available | Request has no dynamic acquisition path. |
| 409 | acquisition_correction_not_allowed | A Resource Request exists but is not in a correctable provider state. |
| 503 | acquisition_requirements_unavailable | Provider requirements are temporarily unavailable. Retry later. |
| 503 | attachment_storage_unavailable | Document storage is temporarily unavailable. |
Next steps
Get Requirements
Verify saved state and provider feedback
Correct Resource Request
Submit the full corrected requirement array