## Update address

`PATCH /v1/addresses/:typeId/:entityTypeId/:entityId`

Updates the fields of an existing address. Pass only the fields you want to change. Full list of fields — [`GET /v1/addresses/fields`](./fields.md).

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `typeId` (path) | number | yes | Address type. Examples: `1` — registered, `8` — delivery, `9` — actual, `11` — beneficiary |
| `entityTypeId` (path) | number | yes | Owner type: `8` — requisite, `3` — contact, `4` — company, `1` — lead |
| `entityId` (path) | number | yes | ID of the address owner. For a requisite — the ID from `GET /v1/requisites` |

## Request fields (body)

| Field | Type | Description |
|------|-----|---------|
| `address1` | string | Street and building |
| `address2` | string | Additional address line |
| `city` | string | City |
| `region` | string | District or region |
| `province` | string | Province or state |
| `postalCode` | string | Postal code |
| `country` | string | Country (text name) |
| `countryCode` | string | Country code (ISO 3166-1 alpha-2, e.g. `US`) |

The fields `typeId`, `entityTypeId`, `entityId` in the request body are ignored — the key is set only in the path.

## Examples

### curl — personal key

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/addresses/11/8/1" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Springfield",
    "address1": "123 Main St",
    "postalCode": "62704"
  }'
```

### curl — OAuth app

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/addresses/11/8/1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Springfield",
    "address1": "123 Main St"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/addresses/11/8/1', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    city: 'Springfield',
    address1: '123 Main St',
    postalCode: '62704',
  }),
})

const { success, data } = await res.json()
```

### JavaScript — OAuth app

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/addresses/11/8/1', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    city: 'Springfield',
    address1: '123 Main St',
  }),
})

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | Update confirmation with an echo of the key |
| `data.typeId` | number | Address type from the path |
| `data.entityTypeId` | number | Owner type from the path |
| `data.entityId` | number | Owner ID from the path |
| `data.updated` | boolean | Always `true` on successful update |

## Response example

```json
{
  "success": true,
  "data": {
    "typeId": 11,
    "entityTypeId": 8,
    "entityId": 1,
    "updated": true
  }
}
```

## Error response example

403 — no `crm` scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_COMPOSITE_KEY` | One or more of the path parameters `typeId`, `entityTypeId`, `entityId` is not a positive integer |
| 400 | `INVALID_REQUEST` | The request body is not an object |
| 404 | `NOT_FOUND` | An address with this composite key was not found |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the update of an existing address |
| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope. This endpoint requires 'crm' scope |
| 401 | `TOKEN_MISSING` | `X-Api-Key` is missing or the key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**The key is in the path, not in the body.** An address is identified by the triple `/:typeId/:entityTypeId/:entityId` in the URL. If you pass `typeId`, `entityTypeId` or `entityId` in the body, they are ignored — the path values take precedence.

**A company's or contact's address is stored on its requisite.** For a company (`4`) and a contact (`3`), the address is attached to their requisite. An update by the company or contact composite key is automatically applied to the matching requisite, so you can update the address by the same key you created and read it with. For a requisite (`8`) and a lead (`1`), the key matches the storage location.

**Address not found — `404`.** If no address exists for the composite key, the endpoint returns `404 NOT_FOUND` and does not perform the update.

## See also

- [Create address](/docs/entities/addresses/create)
- [Get address](/docs/entities/addresses/get)
- [Delete address](/docs/entities/addresses/delete)
- [Address fields](/docs/entities/addresses/fields)
- [Requisites](/docs/entities/requisites)
- [Batch](/docs/batch)