# Identity

The **Identity** entity is recovered from institutions that support this product, accessing details of personal information related to the owner of the connection's account. Recovering this product helps you verify users' identities.

> **Open Finance Fields**
> For Open Finance connectors, additional fields are available including `investorProfile`, `qualifications`, `financialRelationships`, plus a richer set of PF (natural person) and PJ (business) attributes — `socialName`, `sex`, `maritalStatus`, `nationality`, `otherDocuments`, `passport`, `incorporationDate`, `parties`, `businessOtherDocuments`, and `companiesCnpj`. These fields provide enhanced customer data for consented accounts.

```json
{
  "id": "42888436-62f5-49d2-8cf9-e312c7939509",
  "fullName": "Francisco Sousa",
  "companyName": "Pluggy Inc.",
  "document": "123.456.789-00",
  "taxNumber": "38.512.121/0001-95",
  "documentType": "CPF",
  "jobTitle": "Comercial",
  "birthDate": "1991-05-01T00:00:00.000Z",
  "investorProfile": "Moderate",
  "establishmentCode": "001",
  "establishmentName": "Pluggy Establishment",
  "addresses": [
    {
      "fullAddress": "Av. Lucio Costa 1234, Copacabana, Rio de Janeiro, Brasil",
      "country": "Brasil",
      "state": "RJ",
      "city": "Rio de Janeiro",
      "additionalInfo": "Casa amarela",
      "postalCode": "22620-171",
      "primaryAddress": "Av. Lucio Costa, 1234",
      "type": "Personal"
    }
  ],
  "phoneNumbers": [
    {
      "type": "Personal",
      "value": "+54 911 12345678"
    }
  ],
  "emails": [
    {
      "type": "Personal",
      "value": "hello@pluggy.ai"
    }
  ],
  "relations": [
    {
      "type": "CONJUGE",
      "name": "Maria Sousa",
      "document": "098.765.432-10"
    }
  ]
}
```

For Open Finance connectors, the Identity entity carries the extended PF/PJ field set:

```json title="Open Finance"
{
  "id": "42888436-62f5-49d2-8cf9-e312c7939509",
  "itemId": "9b59ab4b-2480-4dfc-9a0d-99b964ba578d",
  "fullName": "Henrique Alexsander Eichstädt",
  "socialName": "Henrique",
  "companyName": "Tech Solutions LTDA",
  "document": "12345678900",
  "taxNumber": "38.512.121/0001-95",
  "documentType": "CPF",
  "jobTitle": "CEO",
  "birthDate": "1985-03-15T00:00:00.000Z",
  "sex": "MALE",
  "maritalStatus": {
    "code": "MARRIED"
  },
  "nationality": {
    "hasBrazilianNationality": true
  },
  "otherDocuments": [
    {
      "type": "CNH",
      "number": "12345678900",
      "checkDigit": "P",
      "additionalInfo": "SSP/SP",
      "expirationDate": "2030-05-21T00:00:00.000Z"
    }
  ],
  "incorporationDate": "2010-01-01T00:00:00.000Z",
  "parties": [
    {
      "type": "PARTNER",
      "personType": "NATURAL_PERSON",
      "documentType": "CPF",
      "documentNumber": "12345678900",
      "civilName": "Henrique Alexsander Eichstädt",
      "startDate": "2010-01-01T00:00:00.000Z",
      "shareholding": 0.51
    }
  ],
  "companiesCnpj": ["38512121000195"],
  "addresses": [
    {
      "fullAddress": "Av. Paulista 1234, Bela Vista, 01310-100, São Paulo, Brasil",
      "country": "Brasil",
      "countryCode": "BRA",
      "state": "SP",
      "city": "São Paulo",
      "district": "Bela Vista",
      "ibgeTownCode": "3550308",
      "postalCode": "01310-100",
      "primaryAddress": "Av. Paulista, 1234",
      "type": "Work",
      "additionalInfo": "Sala 501",
      "geographicCoordinates": {
        "latitude": -23.5614,
        "longitude": -46.6559
      }
    }
  ],
  "phoneNumbers": [
    {
      "type": "Work",
      "value": "+55 (11) 987654321",
      "countryCallingCode": "55",
      "areaCode": "11",
      "extension": "501"
    }
  ],
  "emails": [
    {
      "type": "Work",
      "value": "henrique@techsolutions.com.br"
    }
  ],
  "relations": [],
  "investorProfile": "Moderate",
  "qualifications": {
    "companyCnpj": "38512121000195",
    "occupationCode": "CBO",
    "occupationDescription": "1234-5",
    "informedIncome": {
      "frequency": "ANUAL",
      "amount": 250000,
      "date": "2024-01-01T00:00:00.000Z"
    },
    "informedPatrimony": {
      "amount": 1500000,
      "year": 2024,
      "date": "2024-12-31T00:00:00.000Z"
    },
    "economicActivities": [
      {
        "code": "6201501",
        "isMain": true
      }
    ],
    "informedRevenue": {
      "amount": 500000,
      "frequency": "MONTHLY",
      "year": 2024
    }
  },
  "financialRelationships": {
    "startDate": "2020-05-10T00:00:00.000Z",
    "productsServicesType": [
      "CONTA_DEPOSITO_A_VISTA",
      "CONTA_POUPANCA",
      "OPERACAO_CREDITO"
    ],
    "procurators": [
      {
        "type": "PROCURADOR",
        "cpfNumber": "45678912303",
        "documentNumber": "45678912303",
        "documentType": "CPF",
        "civilName": "Roberto Carlos Mendes Silva",
        "socialName": "Roberto"
      }
    ],
    "accounts": [
      {
        "compeCode": "237",
        "branchCode": "0001",
        "number": "123456",
        "checkDigit": "7",
        "type": "CONTA_DEPOSITO_A_VISTA",
        "subtype": "INDIVIDUAL"
      }
    ],
    "portabilitiesReceived": [
      {
        "employerName": "Acme Inc",
        "employerDocument": "60701190000104",
        "paycheckBankDetainerCnpj": "60701190000204",
        "paycheckBankDetainerIspb": "60701190",
        "portabilityApprovalDate": "2021-03-15T00:00:00.000Z"
      }
    ],
    "paychecksBankLink": [
      {
        "employerName": "Acme Inc",
        "employerDocument": "60701190000104",
        "paycheckBankCnpj": "60701190000204",
        "paycheckBankIspb": "60701190",
        "accountOpeningDate": "2020-01-10T00:00:00.000Z"
      }
    ]
  },
  "createdAt": "2020-09-30T14:38:12.724Z",
  "updatedAt": "2024-12-12T10:30:00.000Z"
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| id | string | No | Primary identifier. |
| fullName | string | No | Full name of the account owner. |
| companyName | string | Yes | Company name (for business accounts). |
| document | string | No | Document number (CPF or CNPJ). |
| taxNumber | string | Yes | Tax identification number. |
| documentType | string | No | Type of the document (CPF, CNPJ). |
| jobTitle | string | Yes | Job title of the account owner. |
| birthDate | string | Yes | Date of birth. |
| investorProfile | string | Yes | Investor profile classification (e.g., Conservative, Moderate, Aggressive). Only available for Open Finance connectors. |
| establishmentCode | string | Yes | Establishment code. |
| establishmentName | string | Yes | Establishment name. |
| addresses | array | Yes | List of addresses associated with the identity. |
| phoneNumbers | array | Yes | List of phone numbers. |
| emails | array | Yes | List of email addresses. |
| relations | array | Yes | List of related persons (e.g., spouse). |
| socialName | string | Yes | Social name of the natural person, if any (PF-only, Open Finance). |
| sex | string | Yes | Sex of the natural person — `FEMALE`, `MALE`, or `OTHER` (PF-only, Open Finance). |
| maritalStatus | [MaritalStatus](#maritalstatus) | Yes | Marital status of the natural person (PF-only, Open Finance). |
| nationality | [Nationality](#nationality) | Yes | Nationality of the natural person (PF-only, Open Finance). |
| otherDocuments | array of [OtherDocument](#otherdocument) | Yes | List of other identification documents held by the natural person — CNH, RG, NIF, RNE, or OTHER (PF-only, Open Finance). |
| passport | [Passport](#passport) | Yes | Passport metadata — applies when the natural person is a non-resident not required to register a CPF (PF-only, Open Finance). |
| incorporationDate | Date | Yes | Date the business was incorporated (PJ-only, Open Finance). |
| parties | array of [BusinessParty](#businessparty) | Yes | Partners and administrators of the business (PJ-only, Open Finance). |
| businessOtherDocuments | array of [BusinessOtherDocument](#businessotherdocument) | Yes | Additional documents for businesses headquartered abroad and not required to register a CNPJ (PJ-only, Open Finance). |
| companiesCnpj | array of string | Yes | CNPJs of the financial institutions responsible for the customer cadastro (Open Finance, PF & PJ). |
| qualifications | [Qualifications](#qualifications) | Yes | Customer qualifications data. Only available for Open Finance connectors. |
| financialRelationships | [FinancialRelationships](#financialrelationships) | Yes | Customer relationship with the institution. Only available for Open Finance connectors. |

## Address

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| fullAddress | string | Yes | Complete address string. |
| country | string | Yes | Country name. |
| countryCode | string | Yes | Country code in alpha3 ISO-3166 format (e.g. `BRA`). Open Finance only. |
| state | string | Yes | State code. |
| city | string | Yes | City name. |
| district | string | Yes | District / neighborhood (bairro). Open Finance only. |
| ibgeTownCode | string | Yes | IBGE municipality code (7 digits). The first two digits identify the Federation Unit. Open Finance only. |
| additionalInfo | string | Yes | Additional information about the address. |
| postalCode | string | Yes | Postal/ZIP code. |
| primaryAddress | string | Yes | Primary street address. |
| type | string | Yes | Type of address (Personal, Work). |
| geographicCoordinates | object | Yes | Geographic coordinates in decimal degrees, WGS84 reference system. Object with `latitude` and `longitude`. Open Finance only. |

## Phone Number

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| type | string | Yes | Type of phone number (Personal, Work or Residencial). |
| value | string | Yes | Phone number value. |
| countryCallingCode | string | Yes | International dialing code (DDI). Populated when different from `55`. Open Finance only. |
| areaCode | string | Yes | Area code (DDD) of the phone. Open Finance only. |
| extension | string | Yes | Extension number, when part of the phone identification. Open Finance only. |
| additionalInfo | string | Yes | Additional info about the phone, e.g. when the source type doesn't fit the standard categories. Open Finance only. |

## Email

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| type | string | Yes | Type of email (Personal, Business). |
| value | string | Yes | Email address value. |

## Relation

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| type | string | Yes | Type of relation (e.g., CONJUGE, PROCURADOR). |
| name | string | Yes | Name of the related person. |
| document | string | Yes | Document number of the related person. |

## MaritalStatus

Marital status of the natural person (PF-only, Open Finance).

```json
{
  "code": "MARRIED",
  "additionalInfo": "Civil partnership"
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| code | string | Yes | `SINGLE`, `MARRIED`, `WIDOWED`, `JUDICIALLY_SEPARATED`, `DIVORCED`, `STABLE_UNION`, or `OTHER`. |
| additionalInfo | string | Yes | Free-text complement. Should be set when `code` is `OTHER`. |

## Nationality

Nationality of the natural person (PF-only, Open Finance).

```json
{
  "hasBrazilianNationality": false,
  "otherNationalities": [
    {
      "countryCode": "ITA",
      "documents": [
        {
          "type": "Passport",
          "number": "YA1234567",
          "country": "ITA",
          "issueDate": "2020-05-30T00:00:00.000Z",
          "expirationDate": "2030-05-30T00:00:00.000Z"
        }
      ]
    }
  ]
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| hasBrazilianNationality | boolean | Yes | Whether the client has Brazilian nationality. |
| otherNationalities | array | Yes | Other nationalities held by the client, if any. |

Each `otherNationalities[]` entry:

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| countryCode | string | Yes | Country code in alpha3 ISO-3166 format. |
| documents | array | Yes | Supporting documents for this nationality. See `NationalityDocument` below. |

Each `documents[]` entry (`NationalityDocument`):

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| type | string | Yes | Document type (free text). Required when the nationality is not Brazilian. |
| number | string | Yes | Document number. Required when the nationality is not Brazilian. |
| country | string | Yes | Country name. |
| issueDate | Date | Yes | Issue date of the document. |
| expirationDate | Date | Yes | Expiration date of the document. |
| additionalInfo | string | Yes | Free-text complement. |

## OtherDocument

Other identification documents the natural person holds (PF-only, Open Finance). Brazilian acronyms are kept verbatim; `OTHER` covers any other type.

```json
{
  "type": "CNH",
  "number": "12345678900",
  "checkDigit": "P",
  "additionalInfo": "SSP/SP",
  "expirationDate": "2030-05-21T00:00:00.000Z"
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| type | string | Yes | `CNH`, `RG`, `NIF`, `RNE`, or `OTHER`. |
| typeAdditionalInfo | string | Yes | Free-text complement. Should be set when `type` is `OTHER`. |
| number | string | Yes | Document number. |
| checkDigit | string | Yes | Check digit of the document, if it has one. |
| additionalInfo | string | Yes | Free-text complement, used to record the issuing authority (e.g. `SSP/SP`) when relevant. |
| expirationDate | Date | Yes | Expiration date of the document. |

## Passport

Passport metadata for the natural person (PF-only, Open Finance). Applies when the client is a non-resident not required to register a CPF.

```json
{
  "number": "YA1234567",
  "country": "ITA",
  "issueDate": "2020-05-30T00:00:00.000Z",
  "expirationDate": "2030-05-30T00:00:00.000Z"
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| number | string | Yes | Passport number. |
| country | string | Yes | Issuing country in alpha3 ISO-3166 format. |
| issueDate | Date | Yes | Issue date of the passport. |
| expirationDate | Date | Yes | Expiration date of the passport. |

## BusinessParty

Partner or administrator of a business (PJ-only, Open Finance). Partners with less than 25% shareholding may be omitted by the institution.

```json
{
  "type": "PARTNER",
  "personType": "NATURAL_PERSON",
  "documentType": "CPF",
  "documentNumber": "12345678900",
  "civilName": "Henrique Alexsander Eichstädt",
  "startDate": "2010-01-01T00:00:00.000Z",
  "shareholding": 0.51
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| type | string | Yes | `PARTNER` (sócio) or `ADMINISTRATOR` (administrador). |
| personType | string | Yes | `NATURAL_PERSON` or `LEGAL_ENTITY`. |
| documentType | string | Yes | `CPF`, `CNPJ`, `PASSPORT`, or `OTHER_TRAVEL_DOCUMENT`. |
| documentNumber | string | Yes | Number of the identification document (digits and check digit, if any). |
| documentCountry | string | Yes | Issuing country of the document, alpha3 ISO-3166. |
| documentExpirationDate | Date | Yes | Expiration date of the document. |
| documentIssueDate | Date | Yes | Issue date of the document. |
| documentAdditionalInfo | string | Yes | Free-text complement when the document carries identification info that doesn't fit the other fields. |
| civilName | string | Yes | Civil name of the party. Required when `personType` is `NATURAL_PERSON`. |
| socialName | string | Yes | Social name of the natural-person party, if any. |
| companyName | string | Yes | Company name of the party. Required when `personType` is `LEGAL_ENTITY`. |
| tradeName | string | Yes | Trade name of the legal-entity party, if any. |
| startDate | Date | Yes | Date the party's participation started. |
| shareholding | number | Yes | Shareholding fraction between 0 and 1 (e.g. `0.51` represents 51%, `1` represents 100%). Required when `type` is `PARTNER` and the shareholding is 25% or higher. |

## BusinessOtherDocument

Additional document for businesses headquartered abroad and not required to register a CNPJ (PJ-only, Open Finance).

```json
{
  "type": "EIN",
  "number": "128328453",
  "country": "USA",
  "expirationDate": "2030-05-21T00:00:00.000Z"
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| type | string | Yes | Type of the document (e.g. `EIN`). |
| number | string | Yes | Document number. |
| country | string | Yes | Issuing country in alpha3 ISO-3166 format. |
| expirationDate | Date | Yes | Expiration date of the document. |

## Qualifications

Customer qualifications data (Open Finance).

```json
{
  "companyCnpj": "38512121000195",
  "occupationCode": "CBO",
  "occupationDescription": "1234-5",
  "informedIncome": {
    "frequency": "ANUAL",
    "amount": 250000,
    "date": "2024-01-01T00:00:00.000Z"
  },
  "informedPatrimony": {
    "amount": 1500000,
    "year": 2024,
    "date": "2024-12-31T00:00:00.000Z"
  },
  "economicActivities": [
    {
      "code": "6201501",
      "isMain": true
    }
  ],
  "informedRevenue": {
    "amount": 500000,
    "frequency": "MONTHLY",
    "year": 2024
  }
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| companyCnpj | string | Yes | CNPJ of the company associated with the qualifications. |
| occupationCode | string | Yes | `RECEITA_FEDERAL`, `CBO`, or `OUTRO`. |
| occupationDescription | string | Yes | Free-text occupation description. Holds the standardized list code when `occupationCode` is `RECEITA_FEDERAL` or `CBO`; the custom description when `OUTRO`. |
| informedIncome | object | Yes | Informed income. Object with `frequency` (`DIARIA`, `SEMANAL`, `QUINZENAL`, `MENSAL`, `BIMESTRAL`, `TRIMESTRAL`, `SEMESTRAL`, `ANUAL`, `OUTROS`), `amount`, and `date`. |
| informedPatrimony | object | Yes | Informed patrimony. Object with `amount`, `year`, and optionally `date` (returned on the PJ business path). |
| economicActivities | array | Yes | CNAE codes describing the economic activities of the business (PJ-only). Each entry has `code` (7-digit CNAE) and `isMain` boolean. |
| informedRevenue | object | Yes | Revenue (faturamento) informed by the business — the business equivalent of `informedIncome` (PJ-only). Object with `amount`, optional `frequency` (`DAILY`, `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIANNUAL`, `ANNUAL`, `OTHER`), `frequencyAdditionalInfo`, and `year`. |

## FinancialRelationships

Customer relationship with the institution (Open Finance).

```json
{
  "startDate": "2020-05-10T00:00:00.000Z",
  "productsServicesType": ["CONTA_DEPOSITO_A_VISTA", "OPERACAO_CREDITO"],
  "procurators": [
    {
      "type": "PROCURADOR",
      "cpfNumber": "45678912303",
      "documentNumber": "45678912303",
      "documentType": "CPF",
      "civilName": "Roberto Carlos Mendes Silva",
      "socialName": "Roberto"
    }
  ],
  "accounts": [
    {
      "compeCode": "237",
      "branchCode": "0001",
      "number": "123456",
      "checkDigit": "7",
      "type": "CONTA_DEPOSITO_A_VISTA",
      "subtype": "INDIVIDUAL"
    }
  ],
  "portabilitiesReceived": [
    {
      "employerName": "Acme Inc",
      "employerDocument": "60701190000104",
      "paycheckBankDetainerCnpj": "60701190000204",
      "paycheckBankDetainerIspb": "60701190",
      "portabilityApprovalDate": "2021-03-15T00:00:00.000Z"
    }
  ],
  "paychecksBankLink": [
    {
      "employerName": "Acme Inc",
      "employerDocument": "60701190000104",
      "paycheckBankCnpj": "60701190000204",
      "paycheckBankIspb": "60701190",
      "accountOpeningDate": "2020-01-10T00:00:00.000Z"
    }
  ]
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| startDate | Date | Yes | Date when the relationship with the institution started. |
| productsServicesType | array of string | Yes | List of products and services that the client consumes (e.g. `CONTA_DEPOSITO_A_VISTA`, `CARTAO_CREDITO`, `OPERACAO_CREDITO`). |
| productsServicesTypeAdditionalInfo | string | Yes | Additional info about the products and services. Populated when `productsServicesType` includes `OUTROS`. |
| procurators | array | Yes | List of procurators. Each entry has `type` (`REPRESENTANTE_LEGAL` or `PROCURADOR`), `cpfNumber` (legacy — may carry a CNPJ on PJ), the canonical `documentNumber` + `documentType` (`CPF` / `CNPJ`) pair, `civilName`, and optional `socialName`. |
| accounts | array | Yes | List of consented accounts. Each entry has `compeCode`, `branchCode`, `number`, `checkDigit`, `type` (`CONTA_DEPOSITO_A_VISTA`, `CONTA_POUPANCA`, `CONTA_PAGAMENTO_PRE_PAGA`), and `subtype` (`INDIVIDUAL`, `CONJUNTA_SIMPLES`, `CONJUNTA_SOLIDARIA`). |
| portabilitiesReceived | array | Yes | Salary portabilities received by the institution from the client's previous paycheck banks (banco-folha). PF-only. See entry schema below. |
| paychecksBankLink | array | Yes | Paycheck-bank (banco-folha) links to employers, active or formerly active. PF-only. See entry schema below. |

Each `portabilitiesReceived[]` entry:

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| employerName | string | Yes | Employer name as received in the portability message. |
| employerDocument | string | Yes | Employer document (CPF or CNPJ) as received in the portability message. |
| paycheckBankDetainerCnpj | string | Yes | CNPJ of the bank that holds the paycheck account (banco-folha). |
| paycheckBankDetainerIspb | string | Yes | ISPB of the bank that holds the paycheck account. |
| portabilityApprovalDate | Date | Yes | Date the portability was approved. |

Each `paychecksBankLink[]` entry:

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| employerName | string | Yes | Employer name as registered when the paycheck account was opened. |
| employerDocument | string | Yes | Employer document (CPF or CNPJ) as registered when the paycheck account was opened. |
| paycheckBankCnpj | string | Yes | CNPJ of the institution contracted to provide the paycheck service (banco-folha). |
| paycheckBankIspb | string | Yes | ISPB of the institution contracted to provide the paycheck service. |
| accountOpeningDate | Date | Yes | Date the paycheck account was opened. |

> See [Identity](/reference/identity) in our API reference for more information.