Skip to main content
List Holders
curl --request GET \
  --url http://127.0.0.1:4003/v1/holders \
  --header 'X-Lerian-Id: <x-lerian-id>' \
  --header 'X-Organization-Id: <x-organization-id>'
{
  "items": [
    {
      "id": "0194f0ea-2cb2-78c9-b9be-704ba20a9cd8",
      "externalId": "d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f",
      "type": "LEGAL_PERSON",
      "name": "ACME Corp LTD",
      "document": "91315026015",
      "addresses": {
        "primary": {
          "line1": "Rua Botucatu 10",
          "line2": "Casa B",
          "zipCode": "04023060",
          "city": "São Paulo",
          "state": "SP",
          "country": "BR",
          "description": "BR address"
        },
        "additional1": {
          "line1": "75020 Odell Grove",
          "line2": "Apt. 181",
          "zipCode": "40969-4460",
          "city": "Rubenport",
          "state": "NH",
          "country": "US",
          "description": "US address"
        },
        "additional2": {
          "line1": "52 Lavender Hill",
          "line2": "Apt. 2",
          "zipCode": "SW11 5RH",
          "city": "Battersea",
          "state": "London",
          "country": "UK",
          "description": "UK address"
        }
      },
      "contact": {
        "primaryEmail": "[email protected]",
        "secondaryEmail": "[email protected]",
        "mobilePhone": "5577927967227",
        "otherPhone": "556829443019"
      },
      "naturalPerson": {
        "favoriteName": "Johnny",
        "socialName": "Johnny Doe",
        "gender": "Male",
        "birthDate": "1990-12-01",
        "civilStatus": "Married",
        "nationality": "Brazilian",
        "motherName": "Jane Doe",
        "fatherName": "Richard Doe",
        "status": "Active"
      },
      "legalPerson": {
        "tradeName": "ACME",
        "activity": "Electronic devices development",
        "type": "Limited Liability",
        "foundingDate": "2010-01-01",
        "size": "Medium",
        "status": "Closed",
        "representative": {
          "name": "Jane Doe",
          "document": "98765432100",
          "email": "[email protected]",
          "role": "CFO"
        }
      },
      "metadata": {
        "metadata1": "value1",
        "metadata2": 2
      },
      "createdAt": "2025-01-01T00:00:00Z",
      "deletedAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": "01954e1e-e42d-79eb-a5a0-04a5bcad8272",
      "externalId": "G4K7N8M2",
      "type": "NATURAL_PERSON",
      "name": "John Doe",
      "document": "91315026015",
      "addresses": {
        "primary": {
          "line1": "Street 1",
          "line2": "Street 2",
          "zipCode": "00000-000",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "description": "Home address"
        },
        "additional1": {
          "line1": "Street 1",
          "line2": "Street 2",
          "zipCode": "00000-000",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "description": "Home address"
        },
        "additional2": {
          "line1": "Street 1",
          "line2": "Street 2",
          "zipCode": "00000-000",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "description": "Home address"
        }
      },
      "contact": {
        "primaryEmail": "[email protected]",
        "secondaryEmail": "[email protected]",
        "mobilePhone": "+1555555555",
        "otherPhone": "+1555555555"
      },
      "naturalPerson": {
        "favoriteName": "John",
        "socialName": "John Doe",
        "gender": "Male",
        "birthDate": "1990-01-01",
        "civilStatus": "Single",
        "nationality": "Brazilian",
        "motherName": "Jane Doe",
        "fatherName": "John Doe",
        "status": "Active"
      },
      "legalPerson": {
        "tradeName": "Lerian Studio",
        "activity": "Electronic devices development",
        "type": "Limited Liability",
        "foundingDate": "2025-01-01",
        "size": "Medium",
        "status": "Closed",
        "representative": {
          "name": "John Doe",
          "document": "91315026015",
          "email": "[email protected]",
          "role": "CFO"
        }
      },
      "metadata": {
        "labore46": true,
        "qui_0": true,
        "suntb6e": "enim reprehenderit aliquip"
      },
      "createdAt": "2025-02-28T19:53:22.221Z",
      "updatedAt": "2025-02-28T19:53:22.221Z",
      "deletedAt": null
    },
    {
      "id": "01954e2e-30c9-7302-a4e9-0cd8279546fe",
      "externalId": "G4K7N8M2",
      "type": "NATURAL_PERSON",
      "name": "John Doe",
      "document": "91315026016",
      "addresses": {
        "additional1": {
          "line1": "Street 1",
          "line2": "Street 2",
          "zipCode": "00000-000",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "description": "Home address"
        }
      },
      "contact": {
        "primaryEmail": "[email protected]",
        "secondaryEmail": "[email protected]",
        "mobilePhone": "+1555555555",
        "otherPhone": "+1555555555"
      },
      "naturalPerson": {
        "favoriteName": "John",
        "socialName": "John Doe",
        "gender": "Male",
        "birthDate": "1990-01-01",
        "civilStatus": "Single",
        "nationality": "Brazilian",
        "motherName": "Jane Doe",
        "fatherName": "John Doe",
        "status": "Active"
      },
      "legalPerson": {
        "tradeName": "Lerian Studio",
        "activity": "Electronic devices development",
        "type": "Limited Liability",
        "foundingDate": "2025-01-01",
        "size": "Medium",
        "status": "Closed",
        "representative": {
          "name": "John Doe",
          "document": "91315026015",
          "email": "[email protected]",
          "role": "CFO"
        }
      },
      "metadata": {
        "elit_80": -56805915.286121026
      },
      "createdAt": "2025-02-28T20:10:04.873Z",
      "updatedAt": "2025-02-28T20:10:04.873Z",
      "deletedAt": null
    }
  ],
  "page": 1,
  "limit": 10
}

Headers

​
Authorization
string

The authorization token. This header is required if your environment has the Access Manager plugin enabled.

​
X-Organization-Id
string
required

The unique identifier of the Organization associated with the request.

​
X-Lerian-Id
string
required

The unique identifier of Lerian's client, generated and assigned by Lerian.

Query Parameters

​
metadata
string

The metadata key provided when the Holder was created.

​
limit
integer
default:10

The maximum number of items to include in the response.

​
page
integer
default:1

The number of the page that you want to retrieve.

​
sort_order
enum<string>

The order used to sort the results.

Available options:
asc,
desc
​
include_deleted
string

If true, the Holders that were logically deleted (soft deleted) will also be included.

​
external_id
string

Filters holders by your system’s ID.

​
document
string

Filters holders by document number.

Response

​
items
array
required

List with the items returned.

​
page
integer
default:1
required

The number of the page returned.

​
limit
integer
default:10
required

The number of items to include in the response.