# List owners

## ▶️ Usage

With the List Owners method, you can:

1. List owners related to a specific link.id (using the link query parameter).
2. Get the details of a specific owners.id (using the id query parameter).
3. [Not Recommended] List all owners related to your Belvo account (without using any query parameters).

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.

## 🚨 Deprecated Fields

This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field.

Endpoint: GET /api/owners/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `link` (string)
    The link.id you want to filter by.

ℹ️ We highly recommend adding the link.id filter in order to improve your performance.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `omit` (string)
    Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.

  - `fields` (string)
    Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.

  - `link__in` (array)
    Return results only for these link.ids.
    Example: ["5722d0ba-69d7-42dc-8ff5-33767b83c5d6"]

  - `id` (string)
    Return information only for this resource id.
    Example: "24ccab1d-3a86-4136-a6eb-e04bf52b356f"

  - `id__in` (array)
    Return information for these resource ids.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `created_at` (string)
    Return items that were last updated in Belvo's database on this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Return items that were last updated in Belvo's database after this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Return items that were last updated in Belvo's database after or on this date (in YYYY-MM-DD format).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Return items that were last updated in Belvo's database before this date (in YYYY-MM-DD format).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Return items that were last updated in Belvo's database before or on this date (in YYYY-MM-DD format).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Return accounts that were last updated in Belvo's database between two dates (in YYYY-MM-DD format). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: ["2022-01-01","2022-12-31"]

  - `email` (string)
    Returns owners whose email address match your query.
    Example: "lopes.d@gmail.com"

  - `display_name__icontains` (string)
    Return owners whose full display name partially matches your query. For example, mar will return results for Mark, Maria, Neymar, Remarque, and so on.
    Example: "Daniela"

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array) — one of:
    An array of either:

  - Owner Individual (OFDA Brazil) objects
  - Owner Business (OFDA Brazil) objects
  - Owner Standard (Multi-Region) objects
  
  > 🚧 One schema type per response
  >
  > The response will contain an array of one of the schema types described above. In other words, there will not be a mix of schema types in the response.
    - Owner Individual (OFDA Brazil):
      - `id` (string, required)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `link` (string,null, required)
        The link.id the data belongs to.
        Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"
      - `internal_identification` (string,null, required)
        The institution's internal identifier for the owner.
        Example: "7e5838e4"
      - `collected_at` (string, required)
        The ISO-8601 timestamp when the data point was collected.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string, required)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `display_name` (string, required)
        The full name of the individual, as provided by the institution.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Jack Oswald White"
      - `social_name` (string,null, required)
        The social name of the individual, as generally accepted by the country.
        Example: "O Piadista"
      - `birth_date` (string, required)
        The individual's date of birth, in YYYY-MM-DD format.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "1988-07-15"
      - `marital_status` (string,null, required)
        The individual's marital status. We return one of the following values:

  - SINGLE
  - MARRIED
  - WIDOWED
  - SEPARATED
  - DIVORCED
  - CIVIL_UNION
  - OTHER
        Enum: "SINGLE", "MARRIED", "WIDOWED", "SEPARATED", "DIVORCED", "CIVIL_UNION", "OTHER"
      - `marital_status_additional_info` (string,null, required)
        Additional information about the individual's marital status.
        Example: "It's complicated"
      - `gender` (string,null, required)
        The individual's gender. We return on of the following values:

  - FEMALE
  - MALE
  - OTHER
        Enum: "FEMALE", "MALE", "OTHER"
      - `companies_id` (array, required)
        The institutions responsible for the creation and verification of the owner.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: ["01773247000103"]
      - `is_local_resident` (boolean, required)
        Boolean to indicate if the individual is a local resident of the country.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: true
      - `document_id` (object, required)
        Information regarding the identification document the owner provided to the bank.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `document_id.document_type` (string, required)
        The type of document the owner provided to the institution to open the account. Common document types are:

🇧🇷 Brazil
- CPF (Cadastro de Pessoas Físicas)
- CNPJ(Cadastro Nacional de Pessoas Jurídicas)

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "CPF"
      - `document_id.document_number` (string, required)
        The document's identification number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "235578435-S"
      - `additional_documents` (array, required)
        Detailed information regarding additional documents provided to prove the individuals ID.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `additional_documents.type` (string,null, required)
        The type of ID document. We return one of the following values:

  - DRIVERS_LICENSE
  - PASSPORT
  - ID_CARD
  - FISCAL_ID
  - FOREIGNER_REGISTRATION_CARD
  - OTHER
  - null
        Enum: "DRIVERS_LICENSE", "PASSPORT", "ID_CARD", "FISCAL_ID", "FOREIGNER_REGISTRATION_CARD", "OTHER", null
      - `additional_documents.type_additional_info` (string,null, required)
        Additional information regarding the document type.

> Note: For Business ID documents, this field must return a value from Brazil's open finance network.
        Example: "Learner's licence"
      - `additional_documents.number` (string, required)
        The ID document's number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "DL-7896829-7"
      - `additional_documents.check_digit` (string, required)
        The check digit of the ID document.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "7"
      - `additional_documents.issue_date` (string,null, required)
        The date the the ID document was issued, in YYYY-MM-DD format.
        Example: "2019-01-01"
      - `additional_documents.expiration_date` (string,null, required)
        The date the the ID document expires, in YYYY-MM-DD format.
        Example: "2019-01-01"
      - `additional_documents.country_of_issuance` (string,null, required)
        The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).

This field must be returned when the type is PASSPORT.
        Example: "CAN"
      - `additional_documents.additional_info` (string,null, required)
        Additional information about the ID document.
        Example: "The document has water damage"
      - `nationalities` (array,null, required)
        Detailed information regarding the individual's nationalities.

Only required to be returned when is_local_resident is set to false.
      - `nationalities.info` (string,null, required)
        The nationality of the individual.
        Example: "CAN"
      - `nationalities.documents` (array, required)
      - `nationalities.documents.type` (string,null, required)
        The type of ID document. We return one of the following values:

  - DRIVERS_LICENSE
  - PASSPORT
  - ID_CARD
  - FISCAL_ID
  - FOREIGNER_REGISTRATION_CARD
  - OTHER
  - null
        Enum: same as `additional_documents.type` in "Owner Individual (OFDA Brazil)" (7 values)
      - `nationalities.documents.number` (string, required)
        The ID document's number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "DL-7896829-7"
      - `nationalities.documents.issue_date` (string,null, required)
        The date the the ID document was issued, in YYYY-MM-DD format.
        Example: "2019-01-01"
      - `nationalities.documents.expiration_date` (string,null, required)
        The date the the ID document expires, in YYYY-MM-DD format.
        Example: "2019-01-01"
      - `nationalities.documents.country_of_issuance` (string,null, required)
        The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).

This field must be returned when the type is PASSPORT.
        Example: "CAN"
      - `nationalities.documents.additional_info` (string,null, required)
        Additional information about the ID document.
        Example: "The document has water damage"
      - `email` (string,null, required)
        The account owner's registered email address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "johndoe@belvo.com"
      - `emails` (array, required)
        Additional list of emails the owner provided.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `emails.is_main` (boolean, required)
        Boolean to indicate if this is the user's main email address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: true
      - `emails.email` (string, required)
        The user's email address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "homen_morcego@gmail.com"
      - `address` (string,null, required)
        The account owner's registered address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Carrer de la Llacuna, 162, 08018 Barcelona"
      - `addresses` (array, required)
        Detailed information regarding the owner's addresses.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `addresses.is_main` (boolean, required)
        Boolean to indicate if this is the user's main address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: true
      - `addresses.address` (string, required)
        The user's address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Av Naburo Ykesaki, 1270"
      - `addresses.additional_info` (string,null, required)
        Additional information regarding the user's address.
        Example: "In between two palm trees"
      - `addresses.district_name` (string,null, required)
        The distrct of the address.
        Example: "CENTRO"
      - `addresses.town` (string, required)
        The user's town.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Brasilia"
      - `addresses.town_code` (string,null, required)
        The seven-digit code for the town, if applicable.

For Brazil, this is the IBGE town code.
        Example: "3550308"
      - `addresses.state` (string,null, required)
        The state that the address is located in.
        Example: "SP"
      - `addresses.postcode` (string, required)
        The postcode of the address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "17500001"
      - `addresses.country_name` (string, required)
        The name of the country.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Brasil"
      - `addresses.country_code` (string,null, required)
        The three-letter country code (ISO-3166 Alpha 3 compliant).
        Example: "BRA"
      - `addresses.latitude` (string,null, required)
        The geographic latitude coordinate.
        Example: "-23.5475000"
      - `addresses.longitude` (string,null, required)
        The geographic longitude coordinate.
        Example: "-46.6361100"
      - `phone_number` (string,null, required)
        The account owner's registered phone number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "+52-XXX-XXX-XXXX"
      - `phone_numbers` (array, required)
        Detailed information regarding the owner's phone numbers.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `phone_numbers.is_main` (boolean, required)
        Boolean to indicate if this is the user's main phone number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: true
      - `phone_numbers.type` (string,null, required)
        The type of phone number. We return one of the following values:

  - LANDLINE
  - MOBILE
  - OTHER
  - null
        Enum: "LANDLINE", "MOBILE", "OTHER", null
      - `phone_numbers.additional_info` (string,null, required)
        Additional information about the phone number.
        Example: "This is their work mobile number."
      - `phone_numbers.number` (string, required)
        The phone number (not including the country, area, or extension codes).

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "29875132"
      - `phone_numbers.country_code` (string,null, required)
        The country dialling code. For example: 351 (no +).
        Example: "351"
      - `phone_numbers.area_code` (string,null, required)
        The area dialling code.
        Example: "21"
      - `phone_numbers.extension` (string,null, required)
        The extension code.
        Example: "932"
      - `filiations` (array, required)
        Information regarding any familial relationships of the individual.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `filiations.type` (string,null, required)
        The familial relationship. We return one of the following values:

  - MOTHER
  - FATHER
  - null
        Enum: "MOTHER", "FATHER", null
      - `filiations.civil_name` (string, required)
        The person's full name.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Bruce Wayne"
      - `filiations.social_name` (string,null, required)
        The person's social name.
        Example: "The Dark Knight"
      - `financial_profile` (object,null, required)
        Information regarding the financial profile of the individual.
      - `financial_profile.company_id` (string,null, required)
        The identifier of the company where the individual is employed.
        Example: "50685362000135"
      - `financial_profile.occupation_code` (string,null, required)
        The area of employment of the individual. We return one of the following values:

  - BRAZIL_PUBLIC_OFFICE
  - BRAZIL_OCCUPATION_CODE
  - OTHER
  - null
        Enum: "BRAZIL_PUBLIC_OFFICE", "BRAZIL_OCCUPATION_CODE", "OTHER", null
      - `financial_profile.occupation_description` (string,null, required)
        Information regarding the individual's occupation.
        Example: "01"
      - `financial_profile.informed_income` (object, required)
        Information regarding the individual's reported income.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `financial_profile.informed_income.frequency` (string,null, required)
        Indicates how often the individual receives their salary. We return one of the following values:

  - DAILY
  - WEEKLY
  - FORTNIGHTLY
  - MONTHLY
  - BIMONTHLY
  - QUARTERLY
  - BIANNUALLY
  - ANNUALLY
  - OTHERS
        Enum: "DAILY", "WEEKLY", "FORTNIGHTLY", "MONTHLY", "BIMONTHLY", "QUARTERLY", "BIANNUALLY", "ANNUALLY", "OTHERS"
      - `financial_profile.informed_income.amount` (number, required)
        The reported income that the individual receives.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: 45391.89
      - `financial_profile.informed_income.currency` (string, required)
        The three-letter currency code (ISO-4217).

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "BRL"
      - `financial_profile.informed_income.date` (string, required)
        Date when the individual last received their salary.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "2020-03-19"
      - `financial_profile.patrimony` (object,null, required)
        Information regarding the individual's reported assets (if available).
      - `financial_profile.patrimony.amount` (number, required)
        The reported assets of the individual.

> Non-nullable: A value must be returned by Brazil's open finance network when the patrimony object is available.
        Example: 45391.89
      - `financial_profile.patrimony.currency` (string, required)
        The three-letter currency code (ISO-4217).

> Non-nullable: A value must be returned by Brazil's open finance network when the patrimony object is available.
        Example: "BRL"
      - `financial_profile.patrimony.year` (integer, required)
        The year that the reported assets applied. 

> Non-nullable: A value must be returned by Brazil's open finance network when the patrimony object is available.
        Example: 2020
      - `financial_relation` (object,null, required)
        Details regarding any additional relationship the individual has with the institution (for example, other accounts or products they have with the institution).
      - `financial_relation.start_date` (string, required)
        The ISO-8601 timestamp when the financial relationship between the individual and the institution started.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "2021-05-21T08:30:00Z"
      - `financial_relation.product_services` (array, required)
        A list of products that the individual has with the institution.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: ["CONTA_DEPOSITO_A_VISTA"]
      - `financial_relation.product_services_additional_info` (string,null, required)
        Additional information regarding the products that the individual has.
        Example: "Joint account with Robin"
      - `financial_relation.procurators` (array, required)
        Information regarding any individuals or companies that can act on behalf of the owner.
      - `financial_relation.procurators.type` (string,null, required)
        The type of representative that can access and make changes to the account. We return one of the following values:

  - LEGAL_REPRESENTATIVE
  - ATTORNEY
  - null
        Enum: "LEGAL_REPRESENTATIVE", "ATTORNEY", null
      - `financial_relation.procurators.civil_name` (string, required)
        The representatives's full name.

> Non-nullable: A value must be returned by Brazil's open finance network if the procurators field is available.
        Example: "Alfred Thaddeus Pennyworth"
      - `financial_relation.procurators.social_name` (string,null, required)
        The person's social name.
        Example: "Alfred Pennyworth"
      - `financial_relation.procurators.document_number` (string, required)
        The document number of the representative.

Note: For individuals, this is Brazil's CPF number. For businesses, this is Brazil's CNPJ number.

> Non-nullable: A value must be returned by Brazil's open finance network if the procurators field is available.
        Example: "73677831148"
      - `financial_relation.products` (array, required)
        Details regarding any additional products that the individual has with the institution.
      - `financial_relation.products.type` (string,null, required)
        The additional products the individual has at the institution. We return one of the following values:

  - SAVINGS_ACCOUNT
  - CHECKING_ACCOUNT
  - null
        Enum: "SAVINGS_ACCOUNT", "CHECKING_ACCOUNT", null
      - `financial_relation.products.subtype` (string,null, required)
        The subtype of the product that the individual has at the institution.

> Non-nullable: A value must be returned by Brazil's open finance network if the products field is available.
        Example: "CONJUNTA_SIMPLES"
      - `financial_relation.products.agency` (string,null, required)
        The branch code where the product was opened.
        Example: "6272"
      - `financial_relation.products.clearing_code` (string, required)
        The banking clearing code for the product.

> Non-nullable: A value must be returned by Brazil's open finance network if the products field is available.
        Example: "001"
      - `financial_relation.products.number` (string, required)
        The account number of the product.

> Non-nullable: A value must be returned by Brazil's open finance network if the procurators field is available.
        Example: "24550245"
      - `financial_relation.products.check_digit` (string, required)
        The check digit of the product's number.

> Non-nullable: A value must be returned by Brazil's open finance network if the products field is available.
        Example: "7"
      - `financial_relation.salary_portability_requests` (array)
        Details regarding any salary portability requests that the individual has made with the institution.

A salary portability is a request to transfer the individual's salary from their employer's 'payroll' bank account to another bank account.

> 📘 
>
> Please note that the receiving bank account cannot terminate a salary portability (or be informed that it has been termnated). Only the employer's payroll bank is able to provide this information. As such, the portabilities listed here may not be up-to-date.
      - `financial_relation.salary_portability_requests.employer_name` (string)
        The name of the employer.
        Example: "ACME Inc."
      - `financial_relation.salary_portability_requests.employer_id_number` (string)
        The CPF or CNPJ of the employer.
        Example: 12345678901
      - `financial_relation.salary_portability_requests.employer_bank_id_number` (string)
        The CNPJ of the employer's bank.
        Example: 12345678901234
      - `financial_relation.salary_portability_requests.employer_bank_code` (string)
        The bank ISPB (Identificador de Sistema de Pagamentos Brasileiros) code of the employer's bank.
        Example: 12345678
      - `financial_relation.salary_portability_requests.portability_approval_date` (string)
        The date the portability request was approved, in YYYY-MM-DD format.
        Example: "2024-04-01"
      - `financial_relation.payroll_accounts` (array)
        Details regarding any payroll bank accounts that are associated with the individual. That is, each time the indivudal has a new employer that they receive a salary from, it should be listed here.

> 📘
>
> Past employers may not close the payroll account for the indiviual. As such, the payroll accounts listed here may not be up-to-date.
      - `financial_relation.payroll_accounts.employer_name` (string)
        The name of the employer.
        Example: "ACME Inc."
      - `financial_relation.payroll_accounts.employer_id_number` (string)
        The CPF or CNPJ of the employer.
        Example: 12345678901
      - `financial_relation.payroll_accounts.employer_bank_id_number` (string)
        The CNPJ of the employer's bank.
        Example: 12345678901234
      - `financial_relation.payroll_accounts.employer_bank_code` (string)
        The bank ISPB (Identificador de Sistema de Pagamentos Brasileiros) code of the employer's bank.
        Example: 12345678
      - `financial_relation.payroll_accounts.account_opening_date` (string)
        The date that the salary bank account was opened, in YYYY-MM-DD format.
        Example: "2024-04-01"
    - Owner Business (OFDA Brazil):
      - `id` (string, required)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `link` (string,null, required)
        The link.id the data belongs to.
        Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"
      - `internal_identification` (string,null, required)
        The institution's internal identifier for the owner.
        Example: "7e5838e4"
      - `collected_at` (string, required)
        The ISO-8601 timestamp when the data point was collected.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string, required)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `company_name` (string, required)
        The full (official) name of the business, as provided by the institution.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Wayne Enterprises"
      - `trade_name` (string,null, required)
        The trade name of the business.
        Example: "WayneCorp"
      - `incorporation_date` (string, required)
        The date that the business was incorporated, in YYYY-MM-DD format.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "1988-07-15"
      - `companies_id` (array, required)
        The institutions responsible for the creation and verification of the owner.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: ["01773247000103"]
      - `document_id` (object, required)
        Information regarding the identification document the owner provided to the bank.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `document_id.document_type` (string, required)
        The type of document the owner provided to the institution to open the account. Common document types are:

🇧🇷 Brazil
- CPF (Cadastro de Pessoas Físicas)
- CNPJ(Cadastro Nacional de Pessoas Jurídicas)

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "CPF"
      - `document_id.document_number` (string, required)
        The document's identification number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "235578435-S"
      - `additional_documents` (array, required)
        Detailed information regarding additional documents provided to prove the business's ID.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `additional_documents.type` (string,null, required)
        The type of ID document. We return one of the following values:

  - DRIVERS_LICENSE
  - PASSPORT
  - ID_CARD
  - FISCAL_ID
  - FOREIGNER_REGISTRATION_CARD
  - OTHER
  - null
        Enum: same as `additional_documents.type` in "Owner Individual (OFDA Brazil)" (7 values)
      - `additional_documents.type_additional_info` (string,null, required)
        Additional information regarding the document type.

> Note: For Business ID documents, this field must return a value from Brazil's open finance network.
        Example: "EIN"
      - `additional_documents.number` (string, required)
        The ID document's number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "DL-7896829-7"
      - `additional_documents.check_digit` (string, required)
        The check digit of the ID document.

> Note: This field is not applicable for Business ID documents and will return null.
      - `additional_documents.issue_date` (string,null, required)
        The date the the ID document was issued, in YYYY-MM-DD format.

> Note: This field is not applicable for Business ID documents and will return null.
      - `additional_documents.expiration_date` (string,null, required)
        The date the the ID document expires, in YYYY-MM-DD format.
        Example: "2019-01-01"
      - `additional_documents.country_of_issuance` (string,null, required)
        The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "CAN"
      - `additional_documents.additional_info` (string,null, required)
        Additional information about the ID document.

> Note: This field is not applicable for Business ID documents and will return null.
      - `email` (string,null, required)
        The account owner's registered email address.
        Example: "johndoe@belvo.com"
      - `emails` (array, required)
        Additional list of emails the owner provided.
      - `emails.is_main` (boolean, required)
        Boolean to indicate if this is the user's main email address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: true
      - `emails.email` (string, required)
        The user's email address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "homen_morcego@gmail.com"
      - `address` (string,null, required)
        The accounts owners registered address.
        Example: "Carrer de la Llacuna, 162, 08018 Barcelona"
      - `addresses` (array, required)
        Detailed information regarding the owner's addresses.
      - `addresses.is_main` (boolean, required)
        Boolean to indicate if this is the user's main address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: true
      - `addresses.address` (string, required)
        The user's address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Av Naburo Ykesaki, 1270"
      - `addresses.additional_info` (string,null, required)
        Additional information regarding the user's address.
        Example: "In between two palm trees"
      - `addresses.district_name` (string,null, required)
        The distrct of the address.
        Example: "CENTRO"
      - `addresses.town` (string, required)
        The user's town.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Brasilia"
      - `addresses.town_code` (string,null, required)
        The seven-digit code for the town, if applicable.

For Brazil, this is the IBGE town code.
        Example: "3550308"
      - `addresses.state` (string,null, required)
        The state that the address is located in.
        Example: "SP"
      - `addresses.postcode` (string, required)
        The postcode of the address.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "17500001"
      - `addresses.country_name` (string, required)
        The name of the country.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "Brasil"
      - `addresses.country_code` (string,null, required)
        The three-letter country code (ISO-3166 Alpha 3 compliant).
        Example: "BRA"
      - `addresses.latitude` (string,null, required)
        The geographic latitude coordinate.
        Example: "-23.5475000"
      - `addresses.longitude` (string,null, required)
        The geographic longitude coordinate.
        Example: "-46.6361100"
      - `phone_number` (string,null, required)
        The account owner's registered phone number.
        Example: "+52-XXX-XXX-XXXX"
      - `phone_numbers` (array, required)
        Detailed information regarding the owner's phone_numbers.
      - `phone_numbers.is_main` (boolean, required)
        Boolean to indicate if this is the user's main phone number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: true
      - `phone_numbers.type` (string,null, required)
        The type of phone number. We return one of the following values:

  - LANDLINE
  - MOBILE
  - OTHER
  - null
        Enum: same as `phone_numbers.type` in "Owner Individual (OFDA Brazil)" (4 values)
      - `phone_numbers.additional_info` (string,null, required)
        Additional information about the phone number.
        Example: "This is their work mobile number."
      - `phone_numbers.number` (string, required)
        The phone number (not including the country, area, or extension codes).

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "29875132"
      - `phone_numbers.country_code` (string,null, required)
        The country dialling code. For example: 351 (no +).
        Example: "351"
      - `phone_numbers.area_code` (string,null, required)
        The area dialling code.
        Example: "21"
      - `phone_numbers.extension` (string,null, required)
        The extension code.
        Example: "932"
      - `parties` (array, required)
        Detailed information regarding the parties allowed to act on the owner's behalf.

> Non-nullable: A value must be returned by Brazil's open finance network.
      - `parties.person_type` (string,null, required)
        The type of person that is an ownership party of the account. We return one of the following values:

  - INDIVIDUAL
  - COMPANY
        Enum: "INDIVIDUAL", "COMPANY"
      - `parties.type` (string,null, required)
        The access type that the person_type has to the account. We return one of the following values:

- MEMBER indicates that the person_type has read access to the account.
- ADMINISTRATOR indicates that the person_type can perform all actions for the account (including transfers).
        Enum: "MEMBER", "ADMINISTRATOR"
      - `parties.display_name` (string,null, required)
        The full name of the individual, as provided by the institution. Only applicable if the person_type is INDIVIDUAL.
        Example: "Jack Oswald White"
      - `parties.social_name` (string,null, required)
        The social name of the individual, as generally accepted by the country. Only applicable if the person_type is INDIVIDUAL.
        Example: "O Piadista"
      - `parties.company_name` (string,null)
        The full (official) name of the business. Only applicable if the person_type is COMPANY.
        Example: "Wayne Enterprises"
      - `parties.trade_name` (string,null, required)
        The trade name of the business. Only applicable if the person_type is COMPANY.
        Example: "WayneCorp"
      - `parties.start_date` (string,null, required)
        The date that the party was added to the account, in YYYY-MM-DD format.
        Example: "2021-07-15"
      - `parties.percentage_type` (number,null, required)
        The party's equity interest.
        Example: 0.51
      - `parties.document_type` (string,null, required)
        The type of ID document the party provided when being added to the account. We return one of the following values:

  - CPF
  - CNPJ
  - OTHER_TRAVEL_DOCUMENT
  - PASSPORT
        Enum: "CPF", "CNPJ", "OTHER_TRAVEL_DOCUMENT", "PASSPORT"
      - `parties.document_number` (string, required)
        The ID document's number.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "DL-7896829-7"
      - `parties.document_issue_date` (string,null, required)
        The date the the ID document was issued, in YYYY-MM-DD format.
        Example: "2019-01-01"
      - `parties.document_expiration_date` (string,null, required)
        The date the the ID document expires, in YYYY-MM-DD format.
        Example: "2019-01-01"
      - `parties.document_country` (string,null, required)
        The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).
        Example: "CAN"
      - `parties.document_additional_info` (string,null, required)
        Additional information regarding the document.
        Example: "Confirmed CPF with their driver's licence."
      - `financial_profile` (object,null, required)
        Information regarding the financial profile of the individual.
      - `financial_profile.economic_activities` (array, required)
        Details regarding the reported economic activities of the business.
      - `financial_profile.economic_activities.is_main` (boolean, required)
        Boolean to indicate whether this is the business's main economic activity.

> Non-nullable: A value must be returned by Brazil's open finance network if the economic_activities field is available.
        Example: true
      - `financial_profile.economic_activities.code` (string, required)
        The code of the economic activity, as given by the country.

> Non-nullable: A value must be returned by Brazil's open finance network if the economic_activities field is available.
        Example: "8599604"
      - `financial_profile.informed_revenue` (object,null, required)
        Information regarding the business's reported revenue.
      - `financial_profile.informed_revenue.frequency` (string,null, required)
        Indicates how often the business declares their revenue. We return one of the following values:
  
  - DAILY
  - WEEKLY
  - FORTNIGHTLY
  - MONTHLY
  - BIMONTHLY
  - QUARTERLY
  - BIANNUALLY
  - ANNUALLY
  - OTHERS
  - null
        Enum: "DAILY", "WEEKLY", "FORTNIGHTLY", "MONTHLY", "BIMONTHLY", "QUARTERLY", "BIANNUALLY", "ANNUALLY", "OTHERS", null
      - `financial_profile.informed_revenue.frequency_additional_info` (string,null, required)
        Additional information regarding the frequency.
        Example: "Recently switched from weekly to monthly."
      - `financial_profile.informed_revenue.amount` (number, required)
        The reported revenue of the business.

> Non-nullable: A value must be returned by Brazil's open finance network if the informed_revenue field is available.
        Example: 45391.89
      - `financial_profile.informed_revenue.currency` (string, required)
        The three-letter currency code (ISO-4217).

> Non-nullable: A value must be returned by Brazil's open finance network if the informed_revenue field is available.
        Example: "BRL"
      - `financial_profile.informed_revenue.year` (integer, required)
        The year when revenue was last declared.

> Non-nullable: A value must be returned by Brazil's open finance network if the informed_revenue field is available.
        Example: 2022
      - `financial_profile.patrimony` (object,null, required)
        Information regarding the individual's reported assets.
      - `financial_profile.patrimony.amount` (number, required)
        The reported assets of the business.

> Non-nullable: A value must be returned by Brazil's open finance network if the patrimony field is available.
        Example: 45391.89
      - `financial_profile.patrimony.currency` (string, required)
        The three-letter currency code (ISO-4217).

> Non-nullable: A value must be returned by Brazil's open finance network if the patrimony field is available.
        Example: "BRL"
      - `financial_profile.patrimony.date` (string, required)
        The date that the reported assets applied, in YYYY-MM-DD format.

> Non-nullable: A value must be returned by Brazil's open finance network if the patrimony field is available.
        Example: "2022-12-12"
      - `financial_relation` (object,null, required)
        Details regarding any additional relationship the business has with the institution (for example, other accounts or products they have with the institution).
      - `financial_relation.start_date` (string, required)
        The ISO-8601 timestamp when the financial relationship between the business and the institution started.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: "2021-05-21T08:30:00Z"
      - `financial_relation.product_services` (array, required)
        A list of products that the business has with the institution.

> Non-nullable: A value must be returned by Brazil's open finance network.
        Example: ["CONTA_DEPOSITO_A_VISTA"]
      - `financial_relation.procurators` (array, required)
        Information regarding any individuals or companies that can act on behalf of the owner.
      - `financial_relation.procurators.type` (string,null, required)
        The type of representative that can access and make changes to the account. We return one of the following values:

  - LEGAL_REPRESENTATIVE
  - ATTORNEY
  - null
        Enum: same as `financial_relation.procurators.type` in "Owner Individual (OFDA Brazil)" (3 values)
      - `financial_relation.procurators.civil_name` (string, required)
        The representatives's full name.

> Non-nullable: A value must be returned by Brazil's open finance network if the procurators field is available.
        Example: "Alfred Thaddeus Pennyworth"
      - `financial_relation.procurators.social_name` (string,null, required)
        The person's social name.
        Example: "Alfred Pennyworth"
      - `financial_relation.procurators.document_number` (string, required)
        The document number of the representative.

Note: For individuals, this is Brazil's CPF number. For businesses, this is Brazil's CNPJ number.

> Non-nullable: A value must be returned by Brazil's open finance network if the procurators field is available.
        Example: "73677831148"
      - `financial_relation.products` (array, required)
        Details regarding any additional products that the business has with the institution.
      - `financial_relation.products.type` (string,null, required)
        The additional products the business has at the institution. We return one of the following values:

  - SAVINGS_ACCOUNT
  - CHECKING_ACCOUNT
  - null
        Enum: same as `financial_relation.products.type` in "Owner Individual (OFDA Brazil)" (3 values)
      - `financial_relation.products.subtype` (string, required)
        The subtype of the product that the business has at the institution.

> Non-nullable: A value must be returned by Brazil's open finance network if the products field is available.
        Example: "CONJUNTA_SIMPLES"
      - `financial_relation.products.agency` (string,null, required)
        The branch code where the product was opened.
        Example: "6272"
      - `financial_relation.products.clearing_code` (string, required)
        The banking clearing code for the product.

> Non-nullable: A value must be returned by Brazil's open finance network if the products field is available.
        Example: "001"
      - `financial_relation.products.number` (string, required)
        The account number of the product.

> Non-nullable: A value must be returned by Brazil's open finance network if the products field is available.
        Example: "24550245"
      - `financial_relation.products.check_digit` (string, required)
        The check digit of the product's number.

> Non-nullable: A value must be returned by Brazil's open finance network if the products field is available.
        Example: "7"
    - Owner Standard (Multi-Region):
      - `id` (string, required)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `link` (string,null, required)
        The link.id the data belongs to.
        Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"
      - `internal_identification` (string,null, required)
        The institution's internal identifier for the owner.
        Example: "7e5838e4"
      - `collected_at` (string, required)
        The ISO-8601 timestamp when the data point was collected.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `display_name` (string,null, required)
        The full name of the owner, as provided by the bank.
        Example: "John Doe"
      - `email` (string,null, required)
        The account owner's registered email address.
        Example: "johndoe@belvo.com"
      - `phone_number` (string,null, required)
        The account owner's registered phone number.
        Example: "+52-XXX-XXX-XXXX"
      - `address` (string,null, required)
        The accounts owners registered address.
        Example: "Carrer de la Llacuna, 162, 08018 Barcelona"
      - `document_id` (object,null)
        Information regarding the identification document the owner provided to the bank.
      - `document_id.document_type` (string,null, required)
        The type of document the owner provided to the institution to open the account. Common document types are:

🇧🇷 Brazil
- CPF (Cadastro de Pessoas Físicas)
- CNPJ(Cadastro Nacional de Pessoas Jurídicas)

🇨🇴 Colombia
- CC(Cédula de Ciudadanía)
- NIT (Número de Identificación Tributaria)

🇲🇽 Mexico
- CURP (Clave Única de Registro de Población)
- NSS (Número de Seguridad Social)
- RFC (Registro Federal de Contribuyentes)
        Example: "CPF"
      - `document_id.document_number` (string,null, required)
        The document's identification number.
        Example: "235578435-S"
      - `business_name` (string,null)
        This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.

The name of the business.
      - `first_name` (string,null)
        This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.

The first name of the account owner.
      - `last_name` (string,null)
        This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.

The last name of the account owner.
      - `second_last_name` (string,null)
        This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.

The second last name of the account owner.

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 428 fields (application/json):

  - `code` (string)
    A unique error code (token_required) that allows you to classify and handle the error programmatically.
ℹ️ Check our DevPortal for more information on how to handle 428 token_required errors.
    Example: "token_required"

  - `message` (string)
    A short description of the error. 
For token_required errors, the description is:
  
  - A MFA token is required by the institution to login.
    Example: "A MFA token is required by the institution to login"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `session` (string)
    A 32-character unique ID of the login session (matching a regex pattern of: [a-f0-9]{32}).
    Example: "2675b703b9d4451f8d4861a3eee54449"

  - `expiry` (integer)
    Session duration time in seconds.
    Example: 9600

  - `link` (string)
    Unique identifier created by Belvo, used to reference the current
Link.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `token_generation_data` (object)
    Details on how to generate the token.

  - `token_generation_data.instructions` (string)
    Instructions for token generation.
    Example: "Use this code to generate the token"

  - `token_generation_data.type` (string)
    Type of the data to generate the token (QR code, numeric
challenge).
    Example: "numeric"

  - `token_generation_data.value` (string)
    Value to use to generate the token.
    Example: "12345"

  - `token_generation_data.expects_user_input` (boolean)
    Indicates whether the user needs to provide input in order to complete the authentication.
When set to false, your user may need to:
- confirm the login on another device
- scan a QR code
You will still need to make a PATCH call to complete the request.
    Example: true

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"