> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Update a person

PATCH https://api-sandbox.payabli.com/api/v2/people/{personReference}
Content-Type: application/json

Applies a partial update to a person. Send only the fields you want to change.

A person's job title belongs to their business link, not the person. Sending `title` in any form, including `null`, returns a `400` with the message `title moved to the business relationship; update it with PATCH /api/v2/businesses/{businessReference}/people/{personReference}.`

Reference: https://docs.payabli.com/developers/api-reference/people/update-a-person

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api-sandbox.payabli.com/api` (Sandbox, default)
- `https://api.payabli.com/api` (Production)

## Request

### Path parameters

- `personReference` (string, required) — The person reference.

### Body (application/json)

This endpoint expects an UpdatePersonRequest.

- `firstName` (string, optional) — The person's first name.
- `middleName` (string, optional) — The person's middle name.
- `lastName` (string, optional) — The person's last name.
- `primaryEmail` (string, optional) — The person's primary email address.
- `secondaryEmail` (string, optional) — The person's secondary email address.
- `primaryPhoneNumber` (string, optional) — The person's primary phone number.
- `secondaryPhoneNumber` (string, optional) — The person's secondary phone number.
- `nationality` (string, optional) — The person's nationality, as a two-letter ISO 3166-1 alpha-2 country code. Nationality selects which identity number applies — `US` uses `ssn`, and any other value uses `nationalIdNumber` and `nationalIdIssuer`.
- `nationalIdIssuer` (string, optional) — The authority that issued the national ID, used when `nationality` is not `US`.
- `driversLicenseNumber` (string, optional) — The person's driver's license number.
- `driversLicenseState` (string, optional) — The two-letter state code for the driver's license.
- `externalId` (string, optional) — Your own identifier for the person.
- `customData` (map from string to any, optional) — Key-value data to merge into the person's stored `customData`. Payabli stores an owner's answers to a boarding template's custom questions under the `templateAnswers` key. When you update a person, Payabli merges `customData` into the stored value, following JSON Merge Patch (RFC 7396). Keys you don't send are kept at every depth, and nested objects merge key by key. Strings, numbers, Boolean values, and arrays replace the stored value, and arrays aren't merged. Send a key as `null` to delete it, such as `{"crmId": null}`. A `customData` that isn't an object, such as an array, replaces the stored value whole. Leave out `customData` to keep it as is. The `customData` you send can be up to 65,536 bytes serialized. The limit applies to the request, not to the merged result.
- `addresses` (list of PersonAddressRequest, optional) — Postal addresses associated with the person.
- `identificationDocuments` (list of IdentificationDocumentRequest, optional) — Government-issued identification documents for the person.

## Response

### 200

Person updated.

- `success` (boolean, required) — Whether the request succeeded.
- `message` (string, required, nullable) — A human-readable result message.
- `traceId` (string, required, nullable) — The trace identifier for the request, useful for support.
- `data` (PersonUpdatedResponse, required, nullable) — The updated person.

## Errors

### 400 Bad Request Error

Bad request / invalid data.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 401 Unauthorized Error

Unauthorized request.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 404 Not Found Error

The requested resource wasn't found.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 500 Internal Server Error

Internal server error.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

## Types

### PersonAddressRequest

An address included in a person request.

- `addressLine1` (string, optional) — The first line of the street address.
- `addressLine2` (string, optional) — The second line of the street address (suite, unit, and so on).
- `cityLocality` (string, optional) — The city or locality.
- `stateProvince` (string, optional) — The two-letter state or province code.
- `postalCode` (string, optional) — The postal or ZIP code.
- `country` (string, optional) — The two-letter ISO 3166-1 alpha-2 country code.
- `type` (enum, optional) — The role the address plays for the person.
  - Allowed values: `legal`, `billing`, `shipping`, `remittance`, `mailing`, `physical`, `residential`

### IdentificationDocumentRequest

A government-issued identification document included in a person request.

- `type` (string, optional) — The document type, for example `drivers_license`, `passport`, or `state_id`.
- `number` (string, optional) — The document number.
- `issuingState` (string, optional) — The two-letter issuing state code.
- `issuingCountry` (string, optional) — The two-letter ISO 3166-1 alpha-2 issuing country code.
- `expirationDate` (string, optional) — The document expiration date.

### PersonUpdatedResponse

The reference and updated timestamp after a person update.

- `personReference` (string, required) — The person reference.
- `lastUpdated` (datetime, required) — When the person was last updated.
- `_links` (PersonLinks, required) — Hypermedia links for the person resource.

### PayabliErrorBodyResponseData

Object with detailed error context.

- `explanation` (string, optional) — Human-readable explanation of what happened.
- `todoAction` (string, optional) — Suggested resolution.

### PersonLinks

Hypermedia links for a person resource.

- `self` (string, optional) — Relative path to the person resource.
- `business` (string, optional) — Relative path to the linked business, present when the person is linked to a business.

## Examples

**Request**

```json
{
  "primaryPhoneNumber": "3055550199"
}
```

**Response**

```json
{
  "success": true,
  "message": "Person updated successfully",
  "traceId": "0HNNQ4R2OT26Q:00000027",
  "data": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "lastUpdated": "2026-08-14T17:27:06.4473841Z",
    "_links": {
      "self": "/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d"
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d"

payload = { "primaryPhoneNumber": "3055550199" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"primaryPhoneNumber":"3055550199"}'
};

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-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d"

	payload := strings.NewReader("{\n  \"primaryPhoneNumber\": \"3055550199\"\n}")

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

	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-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d")

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

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

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-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"primaryPhoneNumber\": \"3055550199\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d', [
  'body' => '{
  "primaryPhoneNumber": "3055550199"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"primaryPhoneNumber\": \"3055550199\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

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

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d")! 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()
```