Skip to main content

​
Overview

Organizations of type organization that want to use Tesouro payment rails must provide information about their key persons as part of payments onboarding. 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, this organization user must have a role with the person permission. If using a partner-level token, no special permissions are needed.

​
Add a person to an organization

To add a person to an organization, call POST /entities/{entity_id}/persons: 
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: 
{
  "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.

​
Retrieve a person

To get information about a specific person associated with the specified organization, call
GET /entities/{entity_id}/persons/{person_id}.

​
Edit a person

To edit an existing person of the specified organization, call
PATCH /entities/{entity_id}/persons/{person_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}.