> ## 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.

# Update International Requirements

> Save request-owned form values and provisioning documents.

Persists dynamic provider answers and request-scoped documents for one account-owned number request. Use only keys returned by [Get International Requirements](/api-reference/v2/number-requests/get-requirements).

<Warning>
  Business Profile documents cannot be referenced or reused. Upload each provisioning document to this NumberRequest.
</Warning>

<Note>
  This endpoint saves local request data. When the provider status asks for changes, call [Correct Resource Request](/api-reference/v2/number-requests/correct-request) to PATCH the same provider request.
</Note>

<Note>
  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](/api-reference/v2/idempotency).
</Note>

## Path parameters

<ParamField path="request_id" type="string" required>
  Number request id.
</ParamField>

## Body

<ParamField body="internationalAcquisitionFormData" type="object">
  Complete form-value object keyed by non-document requirement key. When supplied, it replaces the saved form object. Values must be scalar and are stored as bounded strings.
</ParamField>

<ParamField body="internationalAcquisitionDocuments" type="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`, or `image/webp`;
  * `data`: base64-encoded file bytes.

  A document is at most 5 MB. A request can hold at most 10 documents and 15 MB in total. Declared content type must match the file bytes.
</ParamField>

<ParamField body="internationalAcquisitionDocumentRemovedKeys" type="array">
  Requirement keys whose stored documents should be removed.
</ParamField>

Only these three fields are accepted. `businessProfileDocumentId` is rejected.

## Example

<RequestExample>
  ```python Python theme={null}
  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,
              }
          ],
      },
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Saved theme={null}
  {
    "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": {}
    }
  }
  ```
</ResponseExample>

## 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](/api-reference/v2/number-requests/update-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.                                                                                                                                                  |
| 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.                                                                                                                                                     |
| 503  | `acquisition_requirements_unavailable`  | Provider requirements are temporarily unavailable. Retry later.                                                                                                                              |
| 503  | `attachment_storage_unavailable`        | Document storage is temporarily unavailable.                                                                                                                                                 |

## Next steps

<CardGroup cols={2}>
  <Card title="Get Requirements" icon="list-check" href="/api-reference/v2/number-requests/get-requirements">
    Verify saved state and provider feedback
  </Card>

  <Card title="Correct Resource Request" icon="rotate" href="/api-reference/v2/number-requests/correct-request">
    Submit the full corrected requirement array
  </Card>
</CardGroup>