> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List Holders > Use this endpoint to list all holders under your organization, following a paginated listing pattern. Currently, filtering by specific holder attributes is reserved for internal integrations over gRPC. ## OpenAPI ````yaml /en/openapi/v3-current/CRM.yaml get /v1/holders openapi: 3.1.0 info: title: CRM description: >- The CRM Integration API is a non-transactional component that provides a set of endpoints for managing holders of ledger accounts and their associated data. CRM is designed to organize and expose customer data for use by other components within the system, facilitating efficient integration and data management. version: 3.7.1 servers: - url: https://crm.sandbox.lerian.net security: [] tags: - name: Holders paths: /v1/holders: get: tags: - Holders API summary: List Holders description: >- Use this endpoint to list all holders under your organization, following a paginated listing pattern. Currently, filtering by specific holder attributes is reserved for internal integrations over gRPC. parameters: - name: metadata in: query description: The metadata key provided when the Holder was created. required: false schema: type: string - name: limit in: query description: The maximum number of items to include in the response. required: false schema: type: integer default: 10 - name: page in: query description: The number of the page that you want to retrieve. required: false schema: type: integer default: 1 - name: sort_order in: query description: The order used to sort the results. required: false schema: type: string enum: - asc - desc - name: include_deleted in: query description: >- If `true`, the Holders that were logically deleted (soft deleted) will also be included. required: false schema: type: string - name: external_id in: query description: Filters holders by your system's ID. required: false schema: type: string - name: document in: query description: Filters holders by document number. required: false schema: type: string - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/XOrganizationId' - $ref: '#/components/parameters/XLerianId' responses: '200': description: >- Indicates that the resource was successfully created and the operation was completed as expected. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/HolderResponse' description: List with the items returned. page: type: integer description: The number of the page returned. default: 1 limit: type: integer description: The number of items to include in the response. default: 10 required: - items - page - limit example: 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: john_doe@email.com secondaryEmail: john.doe@workemail.com 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: janedoe@corporate.com 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: john.doe@example.com secondaryEmail: john.doe@example.com 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: john.doe@example.com 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: john.doe@example.com secondaryEmail: john.doe@example.com 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: john.doe@example.com 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: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Error0011: $ref: '#/components/examples/Error0011' Error0015: $ref: '#/components/examples/Error0015' Error0016: $ref: '#/components/examples/Error0016' Error0019: $ref: '#/components/examples/Error0019' Error0020: $ref: '#/components/examples/Error0020' Error0021: $ref: '#/components/examples/Error0021' Error0022: $ref: '#/components/examples/Error0022' headers: {} '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Error0006: $ref: '#/components/examples/Error0006' headers: {} '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: Error0014: $ref: '#/components/examples/Error0014' headers: {} security: [] components: parameters: Authorization: name: Authorization in: header description: >- The authorization token in the 'Bearer ' format. **Important:** This header is required if your environment has Access Manager enabled. For more information, refer to the [Access Manager](/en/access-manager) documentation. required: false schema: type: string XOrganizationId: name: X-Organization-id in: header description: The unique identifier of the Organization associated with the request. required: true schema: type: string example: 019c96a0-0a98-7287-9a31-786e0809c769 XLerianId: name: X-Lerian-Id in: header description: >- The unique identifier of Lerian's client, generated and assigned by Lerian. required: false schema: type: string example: 019c96a0-0a98-7287-9a31-786e0809c769 schemas: HolderResponse: description: Holder's details. type: object properties: id: type: string description: Unique identifier of the Holder. externalId: description: Optional field for linking this Holder to an external system. type: string type: description: |- Defines if the Holder is an individual or a company. * `NATURAL_PERSON` – Individual * `LEGAL_PERSON` – Company type: string enum: - NATURAL_PERSON - LEGAL_PERSON name: type: string description: Full name of the Holder. document: type: string description: Holder's identification number (such as _CPF_ or _CNPJ_). addresses: $ref: '#/components/schemas/Addresses' description: Holder's address information. contact: $ref: '#/components/schemas/Contact' description: Holder's contact information. naturalPerson: $ref: '#/components/schemas/NaturalPerson' description: Information specific to individuals. legalPerson: $ref: '#/components/schemas/LegalPerson' description: Information specific to legal entities. metadata: $ref: '#/components/schemas/Metadata' createdAt: type: string description: Date when the Holder was created. deletedAt: type: string description: Date when the Holder was deleted. updatedAt: type: string description: Date when the Holder was last updated. ErrorMessage: description: The response message error. type: object properties: code: type: string description: A unique, stable identifier for the error. title: type: string description: A brief summary of the issue. message: type: string description: Detailed guidance for resolving the error. Addresses: description: Information about the Holder's address. type: object properties: primary: $ref: '#/components/schemas/Address' description: Details about the primary address. additional1: $ref: '#/components/schemas/Address' additional2: $ref: '#/components/schemas/Address' Contact: description: User's contact information. type: object properties: primaryEmail: description: The primary email used to contact the holder. type: string secondaryEmail: description: The secondary email used to contact the holder. type: string mobilePhone: description: >- The mobile phone number used to contact the holder, including country code. type: string otherPhone: description: Any additional phone number used to contact the holder. type: string NaturalPerson: description: Personal details of an individual (Natural Person). type: object properties: favoriteName: description: Nickname or preferred name. type: string socialName: description: Social name, if different from the legal name. type: string gender: description: Gender identity of the person. type: string birthDate: type: string description: Date of birth in YYYY-MM-DD format. format: date civilStatus: description: 'Civil status — for example: `Single`, `Married`, or `Divorced`.' type: string nationality: description: Nationality, for example, `Brazilian`. type: string motherName: description: Mother's full name. type: string fatherName: description: Father's full name. type: string status: description: Current status of the individual in the system. type: string LegalPerson: description: Information specific to legal entities (companies). type: object properties: activity: description: The type of business or activity the company engages in. type: string foundingDate: description: The date when the company was established. type: string representative: $ref: '#/components/schemas/Representative' description: Details of the company's legal representative. size: description: The size classification of the company. type: string status: description: The current status of the company. type: string tradeName: description: The registered business name of the company, if applicable. type: string type: description: The legal structure of the company. type: string Metadata: type: object additionalProperties: type: string description: >- An object containing key-value pairs to add as metadata, where the field `name` is the key and the field `value` is the value. For example, to add a Cost Center, use 'costCenter': 'BR_11101997'. Address: description: Details about a specific address. type: object properties: line1: description: Street name and building number. type: string line2: description: Extra address details, for example, apartment or suite number. type: string zipCode: description: Postal or ZIP code. type: string city: description: City where the address is located. type: string state: description: State, province, or region. type: string country: description: Two-letter country code (ISO 3166-1 alpha-2). type: string description: description: A label to help identify this address. type: string Representative: description: Details of the company's legal representative. type: object properties: document: description: The document number of the legal representative. type: string email: description: The email address of the legal representative. type: string name: description: The legal representative's name. type: string role: description: The role of the legal representative within the company. type: string examples: Error0011: value: code: CRM-0011 title: Invalid Sort Order message: >- The 'sort_order' field must be 'asc' or 'desc'. Please provide a valid sort order and try again. summary: Invalid Sort Order Error0015: value: code: CRM-0015 title: Bad Request message: >- The server could not understand the request due to malformed syntax. Please check the listed fields and try again. summary: Bad Request Error0016: value: code: CRM-0016 title: Invalid Query Parameter message: >- One or more query parameters are in an incorrect format. Please check the following parameters '%v' and ensure they meet the required format before trying again. summary: Invalid Query Parameter Error0019: value: code: CRM-0019 title: Invalid Metadata Format message: >- The metadata parameter format is invalid. Metadata must be provided in the 'metadata.field=value' format. Please check the documentation for correct usage. summary: Invalid Metadata Format Error0020: value: code: CRM-0020 title: Invalid Metadata Key message: >- The metadata key '%s' contains invalid characters. Metadata keys must use only alphanumeric characters, underscores, and hyphens after the 'metadata.' prefix. summary: Invalid Metadata Key Error0021: value: code: CRM-0021 title: Potentially Unsafe Metadata Value message: >- The metadata value '%s' contains characters that could be used for database injection attacks. Please remove any MongoDB operators (like $where, $regex) from your query. summary: Potentially Unsafe Metadata Value Error0022: value: code: CRM-0022 title: Invalid Header Value message: >- One or more headers have invalid values. Please check the following headers %v and ensure they contain valid UUIDs before trying again. summary: Invalid Header Value Error0006: value: code: CRM-0006 title: Holder ID Not Found message: >- The provided holder ID does not exist in our records. Please verify the holder ID and try again. summary: Holder ID Not Found Error0014: value: code: CRM-0014 title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. summary: Internal Server Error ````