> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Update worker address by type

PATCH https://api.letsdeel.com/rest/people/{worker_id}/addresses/{address_type}
Content-Type: application/json

Partially updates a worker's home or postal address: only fields sent change; a missing address is created (country required). A future effective\_date schedules the change; systems such as Deel IT and PEO payroll are notified when it becomes current. PEO payroll (Prism) sync is asynchronous. Does not change an independent contractor's legal, invoice or payout address, nor EOR contract documents. GP payroll contract addresses: PATCH /rest/gp/workers/\{worker\_id}/address. Must be enabled per organization.

**Token scopes**: `people:write`

**Beta**: this version requires the `X-Beta: true` request header and its contract may change before it is promoted to stable. It is scheduled to become stable on 2027-01-28.

Reference: https://developer.deel.com/api/reference/endpoints/people/update-worker-address-by-type-v-2026-10-28

## Authentication

- `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
- `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

## Servers

- `https://api.letsdeel.com/rest` (Production, default)
- `https://api-staging.letsdeel.com/rest` (Demo)

## Request

### Path parameters

- `worker_id` (string, required) — Unique identifier for a worker.
- `address_type` (enum, required) — The type of the address to update.
  - Allowed values: `HOME`, `POSTAL`

### Headers

- `X-Beta` (enum, required, default: true) — Opts in to the beta version of this endpoint. Must be `true`.
  - Allowed values: `true`

### Body (application/json)

This endpoint expects an object.

- `data` (PeopleWorkerIdAddressesAddressTypePatchRequestBodyContentApplicationJsonSchemaData, required) — Address fields to change, with optional effective date and edit reason.

## Response

### 200

Successful response

- `data` (PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaData, required) — The address version written by the request.

## Errors

### 400 Bad Request Error

Bad request - invalid body, path parameter or field value, or country missing when the address is created.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

### 401 Unauthorized Error

Unauthorized.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

### 403 Forbidden Error

Forbidden - the addresses public API is not enabled for this organization, or the caller cannot edit this address.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

### 404 Not Found Error

Not found - unknown worker, a worker of another organization, address not found, or no jurisdiction for the given state.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

### 409 Conflict Error

Conflict.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

### 412 Precondition Failed Error

Precondition failed - a pending change request must be resolved before a new one is created.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

### 422 Unprocessable Entity Error

Unprocessable entity.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

### 429 Too Many Requests Error

Too many requests.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

### 500 Internal Server Error

Internal server error.

- `errors` (list of PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems, required) — List of errors describing why the request failed

## Types

### PeopleWorkerIdAddressesAddressTypePatchRequestBodyContentApplicationJsonSchemaData

Address fields to change, with optional effective date and edit reason.

- `zip` (string, optional, nullable) — The zip code.
- `city` (string, optional, nullable) — The city.
- `state` (string, optional, nullable) — The state.
- `street` (string, optional, nullable) — The street address.
- `country` (string, optional) — The two-letter country code. Required when the address is created; cannot be null.
- `line_two` (string, optional, nullable) — The second address line.
- `edit_reason` (PeopleWorkerIdAddressesAddressTypePatchRequestBodyContentApplicationJsonSchemaDataEditReason, optional, nullable) — Reason recorded with the change.
- `effective_date` (string, optional) — Date (YYYY-MM-DD) from which the change applies; a future date schedules it.

### PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaData

The address version written by the request.

- `id` (string, required) — Unique identifier of the address.
- `zip` (string, required, nullable) — The zip code.
- `city` (string, required, nullable) — The city.
- `type` (enum, required) — The type of the address.
  - Allowed values: `HOME`, `POSTAL`
- `state` (string, required, nullable) — The state.
- `street` (string, required, nullable) — The street address.
- `country` (string, required) — The two-letter country code.
- `line_two` (string, required, nullable) — The second address line.
- `effective_date` (string, required, nullable) — Date (YYYY-MM-DD) from which this version of the address applies.

### PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItems

- `code` (string, required) — Machine-readable error code
- `message` (string, required) — A description of the returned error
- `details` (PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItemsDetails, optional) — Validation context, present for validation errors only

### PeopleWorkerIdAddressesAddressTypePatchRequestBodyContentApplicationJsonSchemaDataEditReason

Reason recorded with the change.

- `reason_oid` (string, optional) — Public id of the edit reason.
- `additional_info` (string, optional, nullable) — Free-text details about the change.

### PeopleWorkerIdAddressesAddressTypePatchResponsesContentApplicationJsonSchemaErrorsItemsDetails

Validation context, present for validation errors only

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "data": {
    "id": "f7b3b3b3-3b3b-4b3b-8b3b-3b3b3b3b3b3b",
    "zip": "10001",
    "city": "New York",
    "type": "HOME",
    "state": "NY",
    "street": "123 Main St",
    "country": "US",
    "line_two": "Apt 4B",
    "effective_date": "2026-01-01"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/people/d290f1ee-6c54-4b01-90e6-d701748f0851/addresses/HOME"

payload = {}
headers = {
    "X-Beta": "true",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/people/d290f1ee-6c54-4b01-90e6-d701748f0851/addresses/HOME';
const options = {
  method: 'PATCH',
  headers: {
    'X-Beta': 'true',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.letsdeel.com/rest/people/d290f1ee-6c54-4b01-90e6-d701748f0851/addresses/HOME"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-Beta", "true")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.letsdeel.com/rest/people/d290f1ee-6c54-4b01-90e6-d701748f0851/addresses/HOME")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-Beta"] = 'true'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.letsdeel.com/rest/people/d290f1ee-6c54-4b01-90e6-d701748f0851/addresses/HOME")
  .header("X-Beta", "true")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.letsdeel.com/rest/people/d290f1ee-6c54-4b01-90e6-d701748f0851/addresses/HOME', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'X-Beta' => 'true',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/people/d290f1ee-6c54-4b01-90e6-d701748f0851/addresses/HOME");
var request = new RestRequest(Method.PATCH);
request.AddHeader("X-Beta", "true");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Beta": "true",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/people/d290f1ee-6c54-4b01-90e6-d701748f0851/addresses/HOME")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```