> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization persons

> Learn how to provide information about the key persons of organizations of type 'organization'.

## Overview

[Organizations](/finops/guides/organizations/index) of type `organization` that want to use [Tesouro payment rails](/finops/guides/payments/index) must provide information about their key persons as part of [payments onboarding](/finops/guides/payments/onboarding/index). The key persons include the primary representative, business owners, directors, and executives.

## Roles and permissions

To use the `/persons*` endpoints with an [organization user token](/finops/guides/organizations/users#get-organization-user-token), this organization user must have a role with the `person` permission.

If using a [partner-level token](/finops/guides/authentication/client-credentials), no special permissions are needed.

## Add a person to an organization

To add a person to an organization, call [`POST /entities/{entity_id}/persons`](/finops/reference/openapi/entity-persons/post-persons):

```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/entities/{entity_id}/persons' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "address": {
         "country": "US",
         "line1": "123 Congress Ave",
         "line2": "Suite 100",
         "postal_code": "78701",
         "city": "Austin",
         "state": "TX"
       },
       "date_of_birth": "1993-03-14",
       "first_name": "Mary",
       "last_name": "O\'Brien",
       "email": "user@example.com",
       "phone": "+15125551234",
       "relationship": {
         "title": "CEO",
         "representative": false,
         "executive": true,
         "director": false,
         "owner": false,
         "percent_ownership": 10
       },
       "id_number": "NL000099998B57",
       "ssn_last_4": "0001"
     }'
```

Notes:

* An organization can have only one `relationship.representative`.
* `id_number` is an optional field.
* `ssn_last_4` is an optional field required only for US citizens.

The successful response returns the ID assigned to this person, along with the information passed in the request:

```json lines theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2023-03-14T15:08:12.037Z",
  "updated_at": "2023-03-14T15:08:12.037Z",
  "first_name": "Mary",
  "last_name": "O'Brien",
  ...
}
```

## List all persons

To get information about all persons associated with the specified organization, call\
[`GET /entities/{entity_id}/persons`](/finops/reference/openapi/entity-persons/get-persons).

## Retrieve a person

To get information about a specific person associated with the specified organization, call\
[`GET /entities/{entity_id}/persons/{person_id}`](/finops/reference/openapi/entity-persons/get-persons-id).

## Edit a person

To edit an existing person of the specified organization, call\
[`PATCH /entities/{entity_id}/persons/{person_id}`](/finops/reference/openapi/entity-persons/patch-persons-id).

## Delete a person

To delete an existing person from the list of persons associated with the specified organization, call\
[`DELETE /entities/{entity_id}/persons/{person_id}`](/finops/reference/openapi/entity-persons/delete-persons-id).