> 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

# Manage people with the API

> Learn how to create, read, update, and search the people behind a business with the Payabli API

> **Note**
>
> Intelligent boarding is in beta. To opt in, reach out to your Payabli contact.

A person is an individual associated with a business, such as an owner, director, signer, contact, or employee. Use the people API to create and manage those records as you board a paypoint. For how people fit into the wider model, see the [boarding overview](/guides/pay-ops-boarding-object-model-overview).

## Considerations

* The boarding API uses OAuth2. Send a Bearer token on every request. See [OAuth2 authentication](/developers/oauth-authentication).
* A person's `nationality` decides which identity number applies. For `US`, send `ssn`. For any other nationality, send `nationalIdNumber` and `nationalIdIssuer` instead. Creating a person doesn't check these, but an owner needs them to be validated.
* A person's job `title` and signer status (`isSigner`) belong to the person's link with each business. Set them in `businessRelationship` when you create the person, or on the link later. The same person can have a different title at each business.
* Reads mask sensitive fields such as `ssn`, `nationalIdNumber`, `dateOfBirth`, and identification document numbers. Use the unmasked endpoint when you need the raw values.

## Create a person

Send a `POST` request to `/v2/people` with the person's details. Only `firstName` and `lastName` are required. See the [API reference](/developers/api-reference/people/create-a-person) for this endpoint for full documentation.

To link the person to a business as you create them, include a `businessRelationship` object with the `businessReference` and the person's role in `personType`. For an owner, `ownershipPercentage` is required, from 0 to 100. Leave it out for every other role. Application validation holds every role except `Employee` to the owner requirements, so link anyone who doesn't own part of the business, such as a contact, as an `Employee`. The relationship's contact fields and addresses are separate from the person's own top-level contact fields.

### Request

POST [https://api-sandbox.payabli.com/api/v2/people](https://api-sandbox.payabli.com/api/v2/people)

**`CreatePerson`**

```curl CreatePerson
curl -X POST https://api-sandbox.payabli.com/api/v2/people \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "firstName": "Marcus",
  "lastName": "Delgado",
  "middleName": "James",
  "primaryEmail": "marcus.delgado@example.com",
  "secondaryEmail": "m.delgado@example.net",
  "primaryPhoneNumber": "3055551212",
  "secondaryPhoneNumber": "3055559876",
  "dateOfBirth": "1985-03-14",
  "ssn": "412-55-9021",
  "nationality": "US",
  "driversLicenseNumber": "D1234567",
  "driversLicenseState": "FL",
  "externalId": "person-001",
  "customData": {
    "department": "finance"
  },
  "addresses": [
    {
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 400",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33101",
      "country": "US",
      "type": "legal"
    }
  ],
  "identificationDocuments": [
    {
      "type": "passport",
      "number": "X1234567",
      "issuingCountry": "US",
      "expirationDate": "2030-06-30"
    }
  ],
  "businessRelationship": {
    "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "personType": "Owner",
    "ownershipPercentage": 100,
    "isPrimaryController": true,
    "isSigner": true,
    "title": "CEO",
    "primaryEmail": "contact@example.com",
    "secondaryEmail": "contact.alt@example.net",
    "primaryPhoneNumber": "3055551212",
    "secondaryPhoneNumber": "3055559876",
    "billingAddress": {
      "addressLine1": "123 Main Street",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33101",
      "country": "US",
      "type": "billing"
    },
    "mailingAddress": {
      "addressLine1": "456 Oak Avenue",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33102",
      "country": "US",
      "type": "mailing"
    }
  }
}'
```

**`CreatePerson`**

```typescript CreatePerson
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.people.createPerson({
        firstName: "Marcus",
        middleName: "James",
        lastName: "Delgado",
        primaryEmail: "marcus.delgado@example.com",
        secondaryEmail: "m.delgado@example.net",
        primaryPhoneNumber: "3055551212",
        secondaryPhoneNumber: "3055559876",
        dateOfBirth: "1985-03-14",
        ssn: "412-55-9021",
        nationality: "US",
        driversLicenseNumber: "D1234567",
        driversLicenseState: "FL",
        externalId: "person-001",
        customData: {
            department: "finance",
        },
        addresses: [
            {
                addressLine1: "123 Main Street",
                addressLine2: "Suite 400",
                cityLocality: "Miami",
                stateProvince: "FL",
                postalCode: "33101",
                country: "US",
                type: "legal",
            },
        ],
        identificationDocuments: [
            {
                type: "passport",
                number: "X1234567",
                issuingCountry: "US",
                expirationDate: "2030-06-30",
            },
        ],
        businessRelationship: {
            businessReference: "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
            personType: "Owner",
            ownershipPercentage: 100,
            isPrimaryController: true,
            isSigner: true,
            title: "CEO",
            primaryEmail: "contact@example.com",
            secondaryEmail: "contact.alt@example.net",
            primaryPhoneNumber: "3055551212",
            secondaryPhoneNumber: "3055559876",
            billingAddress: {
                addressLine1: "123 Main Street",
                cityLocality: "Miami",
                stateProvince: "FL",
                postalCode: "33101",
                country: "US",
                type: "billing",
            },
            mailingAddress: {
                addressLine1: "456 Oak Avenue",
                cityLocality: "Miami",
                stateProvince: "FL",
                postalCode: "33102",
                country: "US",
                type: "mailing",
            },
        },
    });
}
main();

```

**`CreatePerson`**

```python CreatePerson
from payabli import payabli, PersonAddressRequest, IdentificationDocumentRequest, BusinessRelationshipRequest

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.people.create_person(
    first_name="Marcus",
    middle_name="James",
    last_name="Delgado",
    primary_email="marcus.delgado@example.com",
    secondary_email="m.delgado@example.net",
    primary_phone_number="3055551212",
    secondary_phone_number="3055559876",
    date_of_birth="1985-03-14",
    ssn="412-55-9021",
    nationality="US",
    drivers_license_number="D1234567",
    drivers_license_state="FL",
    external_id="person-001",
    custom_data={
        "department": "finance"
    },
    addresses=[
        PersonAddressRequest(
            address_line_1="123 Main Street",
            address_line_2="Suite 400",
            city_locality="Miami",
            state_province="FL",
            postal_code="33101",
            country="US",
            type="legal",
        )
    ],
    identification_documents=[
        IdentificationDocumentRequest(
            type="passport",
            number="X1234567",
            issuing_country="US",
            expiration_date="2030-06-30",
        )
    ],
    business_relationship=BusinessRelationshipRequest(
        business_reference="019fed1a-3d6e-75d3-a81e-cba3874b0a55",
        person_type="Owner",
        ownership_percentage=100,
        is_primary_controller=True,
        is_signer=True,
        title="CEO",
        primary_email="contact@example.com",
        secondary_email="contact.alt@example.net",
        primary_phone_number="3055551212",
        secondary_phone_number="3055559876",
        billing_address=PersonAddressRequest(
            address_line_1="123 Main Street",
            city_locality="Miami",
            state_province="FL",
            postal_code="33101",
            country="US",
            type="billing",
        ),
        mailing_address=PersonAddressRequest(
            address_line_1="456 Oak Avenue",
            city_locality="Miami",
            state_province="FL",
            postal_code="33102",
            country="US",
            type="mailing",
        ),
    ),
)

```

**`CreatePerson`**

```java CreatePerson
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.people.requests.CreatePersonRequest;
import io.github.payabli.api.types.BusinessRelationshipRequest;
import io.github.payabli.api.types.IdentificationDocumentRequest;
import io.github.payabli.api.types.PersonAddressRequest;
import io.github.payabli.api.types.PersonAddressType;
import io.github.payabli.api.types.PersonType;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Optional;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.people().createPerson(
            CreatePersonRequest
                .builder()
                .firstName("Marcus")
                .lastName("Delgado")
                .middleName("James")
                .primaryEmail("marcus.delgado@example.com")
                .secondaryEmail("m.delgado@example.net")
                .primaryPhoneNumber("3055551212")
                .secondaryPhoneNumber("3055559876")
                .dateOfBirth("1985-03-14")
                .ssn("412-55-9021")
                .nationality("US")
                .driversLicenseNumber("D1234567")
                .driversLicenseState("FL")
                .externalId("person-001")
                .customData(
                    new HashMap<String, Object>() {{
                        put("department", "finance");
                    }}
                )
                .addresses(
                    Optional.of(
                        Arrays.asList(
                            PersonAddressRequest
                                .builder()
                                .addressLine1("123 Main Street")
                                .addressLine2("Suite 400")
                                .cityLocality("Miami")
                                .stateProvince("FL")
                                .postalCode("33101")
                                .country("US")
                                .type(PersonAddressType.LEGAL)
                                .build()
                        )
                    )
                )
                .identificationDocuments(
                    Optional.of(
                        Arrays.asList(
                            IdentificationDocumentRequest
                                .builder()
                                .type("passport")
                                .number("X1234567")
                                .issuingCountry("US")
                                .expirationDate("2030-06-30")
                                .build()
                        )
                    )
                )
                .businessRelationship(
                    BusinessRelationshipRequest
                        .builder()
                        .businessReference("019fed1a-3d6e-75d3-a81e-cba3874b0a55")
                        .personType(PersonType.OWNER)
                        .ownershipPercentage(100.0)
                        .isPrimaryController(true)
                        .isSigner(true)
                        .title("CEO")
                        .primaryEmail("contact@example.com")
                        .secondaryEmail("contact.alt@example.net")
                        .primaryPhoneNumber("3055551212")
                        .secondaryPhoneNumber("3055559876")
                        .billingAddress(
                            PersonAddressRequest
                                .builder()
                                .addressLine1("123 Main Street")
                                .cityLocality("Miami")
                                .stateProvince("FL")
                                .postalCode("33101")
                                .country("US")
                                .type(PersonAddressType.BILLING)
                                .build()
                        )
                        .mailingAddress(
                            PersonAddressRequest
                                .builder()
                                .addressLine1("456 Oak Avenue")
                                .cityLocality("Miami")
                                .stateProvince("FL")
                                .postalCode("33102")
                                .country("US")
                                .type(PersonAddressType.MAILING)
                                .build()
                        )
                        .build()
                )
                .build()
        );
    }
}
```

**`CreatePerson`**

```csharp CreatePerson
using PayabliApi;
using System.Threading.Tasks;
using System.Collections.Generic;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.People.CreatePersonAsync(
            new CreatePersonRequest {
                FirstName = "Marcus",
                MiddleName = "James",
                LastName = "Delgado",
                PrimaryEmail = "marcus.delgado@example.com",
                SecondaryEmail = "m.delgado@example.net",
                PrimaryPhoneNumber = "3055551212",
                SecondaryPhoneNumber = "3055559876",
                DateOfBirth = "1985-03-14",
                Ssn = "412-55-9021",
                Nationality = "US",
                DriversLicenseNumber = "D1234567",
                DriversLicenseState = "FL",
                ExternalId = "person-001",
                CustomData = new Dictionary<string, object?>(){
                    ["department"] = "finance",
                }
                ,
                Addresses = new List<PersonAddressRequest>(){
                    new PersonAddressRequest {
                        AddressLine1 = "123 Main Street",
                        AddressLine2 = "Suite 400",
                        CityLocality = "Miami",
                        StateProvince = "FL",
                        PostalCode = "33101",
                        Country = "US",
                        Type = PersonAddressType.Legal
                    },
                }
                ,
                IdentificationDocuments = new List<IdentificationDocumentRequest>(){
                    new IdentificationDocumentRequest {
                        Type = "passport",
                        Number = "X1234567",
                        IssuingCountry = "US",
                        ExpirationDate = "2030-06-30"
                    },
                }
                ,
                BusinessRelationship = new BusinessRelationshipRequest {
                    BusinessReference = "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
                    PersonType = PersonType.Owner,
                    OwnershipPercentage = 100,
                    IsPrimaryController = true,
                    IsSigner = true,
                    Title = "CEO",
                    PrimaryEmail = "contact@example.com",
                    SecondaryEmail = "contact.alt@example.net",
                    PrimaryPhoneNumber = "3055551212",
                    SecondaryPhoneNumber = "3055559876",
                    BillingAddress = new PersonAddressRequest {
                        AddressLine1 = "123 Main Street",
                        CityLocality = "Miami",
                        StateProvince = "FL",
                        PostalCode = "33101",
                        Country = "US",
                        Type = PersonAddressType.Billing
                    },
                    MailingAddress = new PersonAddressRequest {
                        AddressLine1 = "456 Oak Avenue",
                        CityLocality = "Miami",
                        StateProvince = "FL",
                        PostalCode = "33102",
                        Country = "US",
                        Type = PersonAddressType.Mailing
                    }
                }
            }
        );
    }

}

```

**`CreatePerson`**

```go CreatePerson
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.CreatePersonRequest{
        FirstName: "Marcus",
        LastName: "Delgado",
        MiddleName: payabli.String(
            "James",
        ),
        PrimaryEmail: payabli.String(
            "marcus.delgado@example.com",
        ),
        SecondaryEmail: payabli.String(
            "m.delgado@example.net",
        ),
        PrimaryPhoneNumber: payabli.String(
            "3055551212",
        ),
        SecondaryPhoneNumber: payabli.String(
            "3055559876",
        ),
        DateOfBirth: payabli.String(
            "1985-03-14",
        ),
        Ssn: payabli.String(
            "412-55-9021",
        ),
        Nationality: payabli.String(
            "US",
        ),
        DriversLicenseNumber: payabli.String(
            "D1234567",
        ),
        DriversLicenseState: payabli.String(
            "FL",
        ),
        ExternalId: payabli.String(
            "person-001",
        ),
        CustomData: map[string]any{
            "department": "finance",
        },
        Addresses: []*payabli.PersonAddressRequest{
            &payabli.PersonAddressRequest{
                AddressLine1: payabli.String(
                    "123 Main Street",
                ),
                AddressLine2: payabli.String(
                    "Suite 400",
                ),
                CityLocality: payabli.String(
                    "Miami",
                ),
                StateProvince: payabli.String(
                    "FL",
                ),
                PostalCode: payabli.String(
                    "33101",
                ),
                Country: payabli.String(
                    "US",
                ),
                Type: payabli.PersonAddressTypeLegal.Ptr(),
            },
        },
        IdentificationDocuments: []*payabli.IdentificationDocumentRequest{
            &payabli.IdentificationDocumentRequest{
                Type: payabli.String(
                    "passport",
                ),
                Number: payabli.String(
                    "X1234567",
                ),
                IssuingCountry: payabli.String(
                    "US",
                ),
                ExpirationDate: payabli.String(
                    "2030-06-30",
                ),
            },
        },
        BusinessRelationship: &payabli.BusinessRelationshipRequest{
            BusinessReference: "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
            PersonType: payabli.PersonTypeOwner.Ptr(),
            OwnershipPercentage: payabli.Float64(
                100,
            ),
            IsPrimaryController: payabli.Bool(
                true,
            ),
            IsSigner: payabli.Bool(
                true,
            ),
            Title: payabli.String(
                "CEO",
            ),
            PrimaryEmail: payabli.String(
                "contact@example.com",
            ),
            SecondaryEmail: payabli.String(
                "contact.alt@example.net",
            ),
            PrimaryPhoneNumber: payabli.String(
                "3055551212",
            ),
            SecondaryPhoneNumber: payabli.String(
                "3055559876",
            ),
            BillingAddress: &payabli.PersonAddressRequest{
                AddressLine1: payabli.String(
                    "123 Main Street",
                ),
                CityLocality: payabli.String(
                    "Miami",
                ),
                StateProvince: payabli.String(
                    "FL",
                ),
                PostalCode: payabli.String(
                    "33101",
                ),
                Country: payabli.String(
                    "US",
                ),
                Type: payabli.PersonAddressTypeBilling.Ptr(),
            },
            MailingAddress: &payabli.PersonAddressRequest{
                AddressLine1: payabli.String(
                    "456 Oak Avenue",
                ),
                CityLocality: payabli.String(
                    "Miami",
                ),
                StateProvince: payabli.String(
                    "FL",
                ),
                PostalCode: payabli.String(
                    "33102",
                ),
                Country: payabli.String(
                    "US",
                ),
                Type: payabli.PersonAddressTypeMailing.Ptr(),
            },
        },
    }
    client.People.CreatePerson(
        context.TODO(),
        request,
    )
}

```

**`CreatePerson`**

```php CreatePerson
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\People\Requests\CreatePersonRequest;
use Payabli\Types\PersonAddressRequest;
use Payabli\Types\PersonAddressType;
use Payabli\Types\IdentificationDocumentRequest;
use Payabli\Types\BusinessRelationshipRequest;
use Payabli\Types\PersonType;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->people->createPerson(
    new CreatePersonRequest([
        'firstName' => 'Marcus',
        'middleName' => 'James',
        'lastName' => 'Delgado',
        'primaryEmail' => 'marcus.delgado@example.com',
        'secondaryEmail' => 'm.delgado@example.net',
        'primaryPhoneNumber' => '3055551212',
        'secondaryPhoneNumber' => '3055559876',
        'dateOfBirth' => '1985-03-14',
        'ssn' => '412-55-9021',
        'nationality' => 'US',
        'driversLicenseNumber' => 'D1234567',
        'driversLicenseState' => 'FL',
        'externalId' => 'person-001',
        'customData' => [
            'department' => "finance",
        ],
        'addresses' => [
            new PersonAddressRequest([
                'addressLine1' => '123 Main Street',
                'addressLine2' => 'Suite 400',
                'cityLocality' => 'Miami',
                'stateProvince' => 'FL',
                'postalCode' => '33101',
                'country' => 'US',
                'type' => PersonAddressType::Legal->value,
            ]),
        ],
        'identificationDocuments' => [
            new IdentificationDocumentRequest([
                'type' => 'passport',
                'number' => 'X1234567',
                'issuingCountry' => 'US',
                'expirationDate' => '2030-06-30',
            ]),
        ],
        'businessRelationship' => new BusinessRelationshipRequest([
            'businessReference' => '019fed1a-3d6e-75d3-a81e-cba3874b0a55',
            'personType' => PersonType::Owner->value,
            'ownershipPercentage' => 100,
            'isPrimaryController' => true,
            'isSigner' => true,
            'title' => 'CEO',
            'primaryEmail' => 'contact@example.com',
            'secondaryEmail' => 'contact.alt@example.net',
            'primaryPhoneNumber' => '3055551212',
            'secondaryPhoneNumber' => '3055559876',
            'billingAddress' => new PersonAddressRequest([
                'addressLine1' => '123 Main Street',
                'cityLocality' => 'Miami',
                'stateProvince' => 'FL',
                'postalCode' => '33101',
                'country' => 'US',
                'type' => PersonAddressType::Billing->value,
            ]),
            'mailingAddress' => new PersonAddressRequest([
                'addressLine1' => '456 Oak Avenue',
                'cityLocality' => 'Miami',
                'stateProvince' => 'FL',
                'postalCode' => '33102',
                'country' => 'US',
                'type' => PersonAddressType::Mailing->value,
            ]),
        ]),
    ]),
);

```

**`CreatePerson`**

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

url = URI("https://api-sandbox.payabli.com/api/v2/people")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"Marcus\",\n  \"lastName\": \"Delgado\",\n  \"middleName\": \"James\",\n  \"primaryEmail\": \"marcus.delgado@example.com\",\n  \"secondaryEmail\": \"m.delgado@example.net\",\n  \"primaryPhoneNumber\": \"3055551212\",\n  \"secondaryPhoneNumber\": \"3055559876\",\n  \"dateOfBirth\": \"1985-03-14\",\n  \"ssn\": \"412-55-9021\",\n  \"nationality\": \"US\",\n  \"driversLicenseNumber\": \"D1234567\",\n  \"driversLicenseState\": \"FL\",\n  \"externalId\": \"person-001\",\n  \"customData\": {\n    \"department\": \"finance\"\n  },\n  \"addresses\": [\n    {\n      \"addressLine1\": \"123 Main Street\",\n      \"addressLine2\": \"Suite 400\",\n      \"cityLocality\": \"Miami\",\n      \"stateProvince\": \"FL\",\n      \"postalCode\": \"33101\",\n      \"country\": \"US\",\n      \"type\": \"legal\"\n    }\n  ],\n  \"identificationDocuments\": [\n    {\n      \"type\": \"passport\",\n      \"number\": \"X1234567\",\n      \"issuingCountry\": \"US\",\n      \"expirationDate\": \"2030-06-30\"\n    }\n  ],\n  \"businessRelationship\": {\n    \"businessReference\": \"019fed1a-3d6e-75d3-a81e-cba3874b0a55\",\n    \"personType\": \"Owner\",\n    \"ownershipPercentage\": 100,\n    \"isPrimaryController\": true,\n    \"isSigner\": true,\n    \"title\": \"CEO\",\n    \"primaryEmail\": \"contact@example.com\",\n    \"secondaryEmail\": \"contact.alt@example.net\",\n    \"primaryPhoneNumber\": \"3055551212\",\n    \"secondaryPhoneNumber\": \"3055559876\",\n    \"billingAddress\": {\n      \"addressLine1\": \"123 Main Street\",\n      \"cityLocality\": \"Miami\",\n      \"stateProvince\": \"FL\",\n      \"postalCode\": \"33101\",\n      \"country\": \"US\",\n      \"type\": \"billing\"\n    },\n    \"mailingAddress\": {\n      \"addressLine1\": \"456 Oak Avenue\",\n      \"cityLocality\": \"Miami\",\n      \"stateProvince\": \"FL\",\n      \"postalCode\": \"33102\",\n      \"country\": \"US\",\n      \"type\": \"mailing\"\n    }\n  }\n}"

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

**`CreatePerson`**

```swift CreatePerson
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "firstName": "Marcus",
  "lastName": "Delgado",
  "middleName": "James",
  "primaryEmail": "marcus.delgado@example.com",
  "secondaryEmail": "m.delgado@example.net",
  "primaryPhoneNumber": "3055551212",
  "secondaryPhoneNumber": "3055559876",
  "dateOfBirth": "1985-03-14",
  "ssn": "412-55-9021",
  "nationality": "US",
  "driversLicenseNumber": "D1234567",
  "driversLicenseState": "FL",
  "externalId": "person-001",
  "customData": ["department": "finance"],
  "addresses": [
    [
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 400",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33101",
      "country": "US",
      "type": "legal"
    ]
  ],
  "identificationDocuments": [
    [
      "type": "passport",
      "number": "X1234567",
      "issuingCountry": "US",
      "expirationDate": "2030-06-30"
    ]
  ],
  "businessRelationship": [
    "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "personType": "Owner",
    "ownershipPercentage": 100,
    "isPrimaryController": true,
    "isSigner": true,
    "title": "CEO",
    "primaryEmail": "contact@example.com",
    "secondaryEmail": "contact.alt@example.net",
    "primaryPhoneNumber": "3055551212",
    "secondaryPhoneNumber": "3055559876",
    "billingAddress": [
      "addressLine1": "123 Main Street",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33101",
      "country": "US",
      "type": "billing"
    ],
    "mailingAddress": [
      "addressLine1": "456 Oak Avenue",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33102",
      "country": "US",
      "type": "mailing"
    ]
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/people")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```

The response returns the new person with sensitive fields masked:

### Response (201)

```json
{
  "success": true,
  "message": "Person created successfully",
  "traceId": "0HNNQ4R2OT26Q:0000001D",
  "data": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "firstName": "Marcus",
    "lastName": "Delgado",
    "verificationStatus": "not_started",
    "createdAt": "2026-08-14T17:24:31.3877241Z",
    "lastUpdated": "2026-08-14T17:24:31.3877242Z",
    "_links": {
      "self": "/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d",
      "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "externalId": "person-001",
    "middleName": "James",
    "primaryEmail": "marcus.delgado@example.com",
    "secondaryEmail": "m.delgado@example.net",
    "primaryPhoneNumber": "3055551212",
    "secondaryPhoneNumber": "3055559876",
    "dateOfBirth": "****-**-14",
    "ssn": "***-**-9021",
    "nationality": "US",
    "driversLicenseNumber": "D1***567",
    "driversLicenseState": "FL",
    "customData": {
      "department": "finance"
    },
    "businessRelationship": {
      "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
      "personType": "owner",
      "ownershipPercentage": 100,
      "beneficialOwner": true,
      "isPrimaryController": true,
      "isSigner": true,
      "title": "CEO",
      "primaryEmail": "contact@example.com",
      "secondaryEmail": "contact.alt@example.net",
      "primaryPhoneNumber": "3055551212",
      "secondaryPhoneNumber": "3055559876",
      "billingAddressUuid": "01a0014d-ce1a-7110-9bac-c4c59647a891",
      "mailingAddressUuid": "01a0014d-ce1a-7110-9bac-c4c59647a892"
    }
  }
}
```

The `personReference` in the response is the reference you use to read and manage the person.

### Handle a link that doesn't complete

If linking an owner would push the business's total ownership over 100%, Payabli still creates the person but doesn't complete the link. The request still returns `201`, but `success` is `false`, the person has no `businessRelationship`, and the `warnings` array contains a `LINK_OWNERSHIP_EXCEEDED` entry:

### Response (201)

```json
{
  "success": false,
  "message": "Person created, but the business link did not complete. See warnings for details.",
  "traceId": "0HNONVRI1SQDV:0000001F",
  "data": {
    "personReference": "01a0d492-62c6-7151-9411-86ed90094a97",
    "firstName": "Grace",
    "lastName": "Delgado",
    "verificationStatus": "not_started",
    "createdAt": "2026-09-24T17:59:18.4704404Z",
    "lastUpdated": "2026-09-24T17:59:18.4704404Z",
    "_links": {
      "self": "/v2/people/01a0d492-62c6-7151-9411-86ed90094a97"
    },
    "externalId": null,
    "middleName": null,
    "primaryEmail": null,
    "primaryPhoneNumber": null,
    "dateOfBirth": null,
    "ssn": null,
    "nationality": "US",
    "driversLicenseNumber": null,
    "driversLicenseState": null
  },
  "warnings": [
    {
      "code": "LINK_OWNERSHIP_EXCEEDED",
      "message": "Combined ownership would exceed 100% (existing 100.00%, attempted 50%)."
    }
  ]
}
```

Check `warnings` on every create response, not only the status code. To finish linking the person, first lower an existing owner's `ownershipPercentage` so the total leaves room, then [link the person to the business](/guides/pay-ops-developer-businesses-manage#manage-the-people-on-a-business). While the total is already at 100%, the link request fails with `400`.

## Get a person

Send a `GET` request to `/v2/people/{personReference}`. Sensitive fields such as `ssn` are masked. See the [API reference](/developers/api-reference/people/get-a-person) for this endpoint for full documentation.

### Request

GET [https://api-sandbox.payabli.com/api/v2/people/\{personReference}](https://api-sandbox.payabli.com/api/v2/people/\{personReference})

```curl
curl https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d \
     -H "Authorization: Bearer <token>"
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.people.getPerson("01a0014d-ce1a-7110-9bac-c4c59647a88d");
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.people.get_person(
    person_reference="01a0014d-ce1a-7110-9bac-c4c59647a88d",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.people().getPerson("01a0014d-ce1a-7110-9bac-c4c59647a88d");
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.People.GetPersonAsync(
            "01a0014d-ce1a-7110-9bac-c4c59647a88d"
        );
    }

}

```

```go
package example

import (
    context "context"

    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    client.People.GetPerson(
        context.TODO(),
        "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->people->getPerson(
    '01a0014d-ce1a-7110-9bac-c4c59647a88d',
);

```

```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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

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 = "GET"
request.allHTTPHeaderFields = headers

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()
```

The response returns the person's detail with sensitive fields masked:

### Response (200)

```json
{
  "success": true,
  "message": "Person retrieved successfully",
  "traceId": "0HNNQ4R2OT25J:00000069",
  "data": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "firstName": "Marcus",
    "lastName": "Delgado",
    "verificationStatus": "not_started",
    "createdAt": "2026-08-14T17:24:31.387724",
    "lastUpdated": "2026-08-14T17:24:31.387724",
    "_links": {
      "self": "/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d"
    },
    "externalId": "person-001",
    "middleName": "James",
    "primaryEmail": "marcus.delgado@example.com",
    "secondaryEmail": "m.delgado@example.net",
    "primaryPhoneNumber": "3055551212",
    "secondaryPhoneNumber": "3055559876",
    "dateOfBirth": "****-**-14",
    "ssn": "***-**-9021",
    "nationality": "US",
    "driversLicenseNumber": "D1***567",
    "driversLicenseState": "FL",
    "customData": {
      "department": "finance"
    },
    "addresses": [
      {
        "addressLine1": "123 Main Street",
        "addressLine2": "Suite 400",
        "cityLocality": "Miami",
        "stateProvince": "FL",
        "postalCode": "33101",
        "country": "US",
        "type": "legal"
      }
    ],
    "identificationDocuments": [
      {
        "type": "passport",
        "number": "****4567",
        "issuingCountry": "US",
        "expirationDate": "2030-06-30"
      }
    ]
  }
}
```

## Get unmasked person detail

To read the raw values of masked fields, send a `GET` request to `/v2/people/{personReference}/unmasked`. See the [API reference](/developers/api-reference/people/get-a-person-unmasked) for this endpoint for full documentation.

### Request

GET [https://api-sandbox.payabli.com/api/v2/people/\{personReference}/unmasked](https://api-sandbox.payabli.com/api/v2/people/\{personReference}/unmasked)

```curl
curl https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d/unmasked \
     -H "Authorization: Bearer <token>"
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.people.getPersonUnmasked("01a0014d-ce1a-7110-9bac-c4c59647a88d");
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.people.get_person_unmasked(
    person_reference="01a0014d-ce1a-7110-9bac-c4c59647a88d",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.people().getPersonUnmasked("01a0014d-ce1a-7110-9bac-c4c59647a88d");
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.People.GetPersonUnmaskedAsync(
            "01a0014d-ce1a-7110-9bac-c4c59647a88d"
        );
    }

}

```

```go
package example

import (
    context "context"

    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    client.People.GetPersonUnmasked(
        context.TODO(),
        "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->people->getPersonUnmasked(
    '01a0014d-ce1a-7110-9bac-c4c59647a88d',
);

```

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

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d/unmasked")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```

The response returns the same detail with sensitive fields unmasked:

### Response (200)

```json
{
  "success": true,
  "message": "Person retrieved successfully",
  "traceId": "0HNNQ4R2OT26Q:0000001E",
  "data": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "firstName": "Marcus",
    "lastName": "Delgado",
    "verificationStatus": "not_started",
    "createdAt": "2026-08-14T17:24:31.387724",
    "lastUpdated": "2026-08-14T17:24:31.387724",
    "_links": {
      "self": "/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d"
    },
    "externalId": "person-001",
    "middleName": "James",
    "primaryEmail": "marcus.delgado@example.com",
    "secondaryEmail": "m.delgado@example.net",
    "primaryPhoneNumber": "3055551212",
    "secondaryPhoneNumber": "3055559876",
    "dateOfBirth": "1985-03-14",
    "ssn": "412-55-9021",
    "nationality": "US",
    "driversLicenseNumber": "D1234567",
    "driversLicenseState": "FL",
    "customData": {
      "department": "finance"
    },
    "addresses": [
      {
        "addressLine1": "123 Main Street",
        "addressLine2": "Suite 400",
        "cityLocality": "Miami",
        "stateProvince": "FL",
        "postalCode": "33101",
        "country": "US",
        "type": "legal"
      }
    ],
    "identificationDocuments": [
      {
        "type": "passport",
        "number": "X1234567",
        "issuingCountry": "US",
        "expirationDate": "2030-06-30"
      }
    ]
  }
}
```

## List people

Send a `GET` request to `/v2/people`. Filter and page the results with the query parameters: `name`, `email`, `verificationStatus`, `limit`, `page`, `sortBy`, and `sortOrder`. See the [API reference](/developers/api-reference/people/list-people) for this endpoint for full documentation.

### Request

GET [https://api-sandbox.payabli.com/api/v2/people](https://api-sandbox.payabli.com/api/v2/people)

```curl
curl -G https://api-sandbox.payabli.com/api/v2/people \
     -H "Authorization: Bearer <token>" \
     -d limit=1 \
     -d page=1
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.people.listPeople({
        limit: 1,
        page: 1,
    });
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.people.list_people(
    limit=1,
    page=1,
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.people.requests.ListPeoplePeopleRequest;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.people().listPeople(
            ListPeoplePeopleRequest
                .builder()
                .limit(1)
                .page(1)
                .build()
        );
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.People.ListPeopleAsync(
            new ListPeoplePeopleRequest {
                Limit = 1,
                Page = 1
            }
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.ListPeoplePeopleRequest{
        Limit: payabli.Int(
            1,
        ),
        Page: payabli.Int(
            1,
        ),
    }
    client.People.ListPeople(
        context.TODO(),
        request,
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\People\Requests\ListPeoplePeopleRequest;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->people->listPeople(
    new ListPeoplePeopleRequest([
        'limit' => 1,
        'page' => 1,
    ]),
);

```

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

url = URI("https://api-sandbox.payabli.com/api/v2/people?limit=1&page=1")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/people?limit=1&page=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```

The response returns a page of people with pagination metadata:

### Response (200)

```json
{
  "success": true,
  "message": "People retrieved successfully",
  "traceId": "0HNNQ4R2OT25J:0000005A",
  "data": {
    "data": [
      {
        "_links": {
          "self": "/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d"
        },
        "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
        "firstName": "Marcus",
        "lastName": "Delgado",
        "verificationStatus": "notstarted",
        "createdAt": "2026-08-14T17:24:31.387724",
        "lastUpdated": "2026-08-14T17:24:31.387724",
        "email": "marcus.delgado@example.com"
      }
    ],
    "pagination": {
      "page": 1,
      "totalPages": 1587,
      "totalRecords": 1587,
      "pageSize": 1,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}
```

## Update a person

Send a `PATCH` request to `/v2/people/{personReference}` with only the fields you want to change. See the [API reference](/developers/api-reference/people/update-a-person) for this endpoint for full documentation.

You can't change `ssn`, `nationalIdNumber`, or `dateOfBirth` after you create a person, so set them correctly when you create the person.

### Request

PATCH [https://api-sandbox.payabli.com/api/v2/people/\{personReference}](https://api-sandbox.payabli.com/api/v2/people/\{personReference})

```curl
curl -X PATCH https://api-sandbox.payabli.com/api/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "primaryPhoneNumber": "3055550199"
}'
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.people.updatePerson("01a0014d-ce1a-7110-9bac-c4c59647a88d", {
        primaryPhoneNumber: "3055550199",
    });
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.people.update_person(
    person_reference="01a0014d-ce1a-7110-9bac-c4c59647a88d",
    primary_phone_number="3055550199",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.people.requests.UpdatePersonRequest;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.people().updatePerson(
            "01a0014d-ce1a-7110-9bac-c4c59647a88d",
            UpdatePersonRequest
                .builder()
                .primaryPhoneNumber("3055550199")
                .build()
        );
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.People.UpdatePersonAsync(
            personReference: "01a0014d-ce1a-7110-9bac-c4c59647a88d",
            request: new UpdatePersonRequest {
                PrimaryPhoneNumber = "3055550199"
            }
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.UpdatePersonRequest{
        PrimaryPhoneNumber: payabli.String(
            "3055550199",
        ),
    }
    client.People.UpdatePerson(
        context.TODO(),
        "01a0014d-ce1a-7110-9bac-c4c59647a88d",
        request,
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\People\Requests\UpdatePersonRequest;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->people->updatePerson(
    '01a0014d-ce1a-7110-9bac-c4c59647a88d',
    new UpdatePersonRequest([
        'primaryPhoneNumber' => '3055550199',
    ]),
);

```

```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
```

```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()
```

The response confirms the update and returns the new timestamp:

### Response (200)

```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"
    }
  }
}
```

## Search people

Send a `POST` request to `/v2/people/search` with at least one of `firstName` or `lastName`. Pass your organization's entry name in the `entry` query parameter and its ID in `orgId`. Both are required. The entry name is `OrgEntryName` in the [organization details](/developers/api-reference/organization/get-organization). If you pass a paypoint's entry name instead, the search covers only that paypoint's business. See the [API reference](/developers/api-reference/search-people) for this endpoint for full documentation.

Use search during boarding to check whether a person already exists in your organization, linked to another business, before you create them. It matches on identity details such as name, date of birth, email, and SSN. An external identity vendor can also enrich the results. To read the people already on the business, [list the business's people](/developers/api-reference/businesses/list-business-people) instead.

### Request

POST [https://api-sandbox.payabli.com/api/v2/people/search](https://api-sandbox.payabli.com/api/v2/people/search)

```curl
curl -X POST "https://api-sandbox.payabli.com/api/v2/people/search?entry=8cfec329267&orgId=123" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "firstName": "Marcus",
  "lastName": "Delgado"
}'
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.people.searchPeople({
        entry: "8cfec329267",
        orgId: 123,
        body: {
            firstName: "Marcus",
            lastName: "Delgado",
        },
    });
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.people.search_people(
    entry="8cfec329267",
    org_id=123,
    request={"firstName": "Marcus", "lastName": "Delgado"},
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.people.requests.SearchPeopleRequest;
import io.github.payabli.api.types.PeopleSearchRequest;
import java.util.HashMap;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.people().searchPeople(
            SearchPeopleRequest
                .builder()
                .entry("8cfec329267")
                .orgId(123L)
                .body(
                    PeopleSearchRequest.of(new 
                    HashMap<String, Object>() {{put("firstName", "Marcus");
                        put("lastName", "Delgado");
                    }})
                )
                .build()
        );
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;
using System.Collections.Generic;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.People.SearchPeopleAsync(
            new SearchPeopleRequest {
                Entry = "8cfec329267",
                OrgId = 123L,
                Body = new Dictionary<string, object>()
                {
                    ["firstName"] = "Marcus",
                    ["lastName"] = "Delgado",
                }

            }
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.SearchPeopleRequest{
        Entry: "8cfec329267",
        OrgId: int64(123),
        Body: &payabli.PeopleSearchRequest{
            Unknown: map[string]any{
                "firstName": "Marcus",
                "lastName": "Delgado",
            },
        },
    }
    client.People.SearchPeople(
        context.TODO(),
        request,
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\People\Requests\SearchPeopleRequest;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->people->searchPeople(
    new SearchPeopleRequest([
        'entry' => '8cfec329267',
        'orgId' => 123,
        'body' => [
            'firstName' => "Marcus",
            'lastName' => "Delgado",
        ],
    ]),
);

```

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

url = URI("https://api-sandbox.payabli.com/api/v2/people/search?entry=8cfec329267&orgId=123")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"Marcus\",\n  \"lastName\": \"Delgado\"\n}"

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

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "firstName": "Marcus",
  "lastName": "Delgado"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/people/search?entry=8cfec329267&orgId=123")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```

The response returns each match with a `matchScore`, plus the total count. A result with `isFromVendor` set to `true` came only from the identity vendor and has no `personReference`:

### Response (200)

```json
{
  "success": true,
  "message": "People search completed",
  "traceId": "0HNONVR8FH4GO:00000030",
  "data": {
    "results": [
      {
        "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
        "firstName": "Marcus",
        "lastName": "Delgado",
        "dateOfBirth": "****-**-14",
        "primaryEmail": "marcus.delgado@example.com",
        "primaryPhone": "+13055551212",
        "riskDecision": null,
        "matchScore": 0.6,
        "isTopMatch": true,
        "isFromVendor": false,
        "phones": [
          "+13055551212"
        ],
        "emails": [
          "marcus.delgado@example.com"
        ],
        "addressCount": 0,
        "phoneCount": 1,
        "emailCount": 1
      }
    ],
    "total": 1,
    "isEnrichedByVendor": false
  }
}
```

Search results mask each person's `dateOfBirth`. To get the full value, send the same request to `/v2/people/search/unmasked`. See the [API reference](/developers/api-reference/search-people-unmasked) for this endpoint for full documentation.

## Link a person to a business

A person can be linked to more than one business. To link someone you've already created, or to change or remove a link, use the people endpoints under the business. See [Manage the people on a business](/guides/pay-ops-developer-businesses-manage#manage-the-people-on-a-business).

## Related resources

See these related resources to help you get the most out of Payabli.

#### References

* **[Required fields for boarding applications](/guides/pay-ops-boarding-kyc-fields-overview)** - Learn more about the Know Your Customer (KYC) and Know Your Business (KYB) fields required for merchant boarding

#### Related topics

* **[Intelligent boarding overview](/guides/pay-ops-boarding-object-model-overview)** - Understand the objects and application lifecycle behind intelligent boarding paypoints on Payabli
* **[Manage business entities with the API](/guides/pay-ops-developer-businesses-manage)** - Learn how to create, read, update, and deactivate boarding business entities with the Payabli API