> ## 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 Number Request

> Update request-owned identity and program fields while provisioning is editable.

Updates an account-owned number request before provider identity is locked. Send only fields that need to change; the server merges them with the stored request and validates the complete result.

<Warning>
  Carrier identity cannot be changed after an Infobip brand id exists or the brand-registration step completed. The API returns `carrier_identity_locked` with reset and reprovision guidance.
</Warning>

<Note>
  `phoneNumberType` is immutable. `targetCountries` can change only before a Resource Request exists. Changing it before that point clears stale international form values, documents, feedback, and status.
</Note>

<Note>
  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.
</Note>

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

## Path parameters

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

## Body

The body accepts the request-owned fields from [Create Number Request](/api-reference/v2/number-requests/create-request), including:

* `brandName`, `companyLegalName`, `taxId`, and `identifierType`;
* business address and carrier contacts;
* `websiteUrl`, `optInFormUrl`, and `termsConditionsUrl`;
* `targetCountries`, messaging program fields, and volume.

`businessProfileId` is never accepted. `taxId` remains write-only in the response.

## Example

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

<ResponseExample>
  ```json 200 — Updated theme={null}
  {
    "request": {
      "id": "665f0a1b2c3d4e5f60718293",
      "addressCountry": "GB",
      "identifierType": "vat",
      "targetCountries": ["US"],
      "status": "pending",
      "provisioningStatus": "failed",
      "updatedAt": "2026-08-03T22:15:00"
    }
  }
  ```
</ResponseExample>

## Error codes

| HTTP | Code                                 | Meaning                                                                    |
| ---- | ------------------------------------ | -------------------------------------------------------------------------- |
| 400  | `business_profile_not_allowed`       | Remove `businessProfileId`; Business Profile data is gate-only.            |
| 400  | `target_countries_invalid`           | The merged request does not contain exactly one target.                    |
| 403  | `business_verification_required`     | The account has no verified business.                                      |
| 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 brand identity already exists; reset and reprovision is required. |
| 409  | `request_not_editable`               | Provisioning is active.                                                    |
| 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  | `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.                             |

Identifier errors include `allowedIdentifierTypes` when choices are available.

## Next steps

<CardGroup cols={2}>
  <Card title="Get Number Request" icon="magnifying-glass" href="/api-reference/v2/number-requests/get-request">
    Verify the persisted request
  </Card>

  <Card title="Correct Resource Request" icon="rotate" href="/api-reference/v2/number-requests/correct-request">
    Return requested provider changes on the same id
  </Card>
</CardGroup>