{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/pluggy/main/json-schema/pluggy-identity-response-schema.json",
  "title": "IdentityResponse",
  "description": "Response with details personal information related to the owner of the connection's account",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pluggy-api-openapi.yml#/components/schemas/IdentityResponse",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the identity to retrieve"
    },
    "itemId": {
      "type": "string",
      "description": "Identifier of the item linked to the identity",
      "format": "uuid"
    },
    "birthDate": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Date of birth"
    },
    "taxNumber": {
      "type": [
        "string",
        "null"
      ],
      "description": "The tax ID (CNPJ) associated with the business account"
    },
    "document": {
      "type": [
        "string",
        "null"
      ],
      "description": "Primary document that identifies the owner"
    },
    "documentType": {
      "type": [
        "string",
        "null"
      ],
      "description": "Type of document collected"
    },
    "jobTitle": {
      "type": [
        "string",
        "null"
      ],
      "description": "Profession or Job information"
    },
    "fullName": {
      "type": [
        "string",
        "null"
      ],
      "description": "Name of the owner of the account"
    },
    "establishmentCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "Establishment code (only for PAYMENT_ACCOUNT connectors)"
    },
    "establishmentName": {
      "type": [
        "string",
        "null"
      ],
      "description": "Name of the establishment (only for PAYMENT_ACCOUNT connectors)"
    },
    "companyName": {
      "type": [
        "string",
        "null"
      ],
      "description": "For business connector, the name of the business"
    },
    "phoneNumbers": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/PhoneNumber"
      },
      "description": "List of phone numbers related to the account"
    },
    "emails": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/Email"
      },
      "description": "List of email addresses related to the account"
    },
    "addresses": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/Address"
      },
      "description": "List of addresses related to the account"
    },
    "relations": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/IdentityRelation"
      },
      "description": "List of names related to the account"
    },
    "investorProfile": {
      "enum": [
        "Conservative",
        "Moderate",
        "Aggressive",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "description": "Is a rating that indicates the investor personality and motivation for investing"
    },
    "qualifications": {
      "type": [
        "object",
        "null"
      ],
      "description": "Information that allows understanding since when the consulted person has been a client of the institution, as well as an indicator of the products and services they currently consume and their representatives",
      "required": [
        "companyCnpj"
      ],
      "properties": {
        "companyCnpj": {
          "type": "string",
          "description": "CNPJ of the company"
        },
        "occupationCode": {
          "type": "string",
          "enum": [
            "RECEITA_FEDERAL",
            "CBO",
            "OUTRO"
          ],
          "description": "Occupation code"
        },
        "occupationDescription": {
          "type": "string",
          "description": "Free-text occupation description. When occupationCode is RECEITA_FEDERAL or CBO it holds the standardized list code; when OUTRO it describes the occupation in cases where the institution does not follow the Receita Federal nor the CBO list"
        },
        "informedIncome": {
          "type": "object",
          "description": "Informed income",
          "required": [
            "frequency",
            "amount",
            "date"
          ],
          "properties": {
            "frequency": {
              "type": "string",
              "enum": [
                "DIARIA",
                "SEMANAL",
                "QUINZENAL",
                "MENSAL",
                "BIMESTRAL",
                "TRIMESTRAL",
                "SEMESTRAL",
                "ANUAL",
                "OUTROS"
              ],
              "description": "Frequency of the informed income"
            },
            "amount": {
              "type": "number",
              "description": "Amount of the informed income"
            },
            "date": {
              "type": "string",
              "format": "date-time",
              "description": "Date when the income was informed"
            }
          }
        },
        "informedPatrimony": {
          "type": "object",
          "description": "Informed patrimony",
          "required": [
            "amount",
            "year"
          ],
          "properties": {
            "amount": {
              "type": "number",
              "description": "Amount of the informed patrimony"
            },
            "year": {
              "type": "number",
              "description": "Year of the patrimony"
            },
            "date": {
              "type": "string",
              "format": "date-time",
              "description": "Reference date of the patrimony. Returned on the business path of Open Finance, where the source field is a full date rather than just a year"
            }
          }
        },
        "economicActivities": {
          "type": "array",
          "description": "List of CNAE codes describing the economic activities of the business (Brazilian National Classification of Economic Activities). Only one entry per response should be marked as main",
          "items": {
            "$ref": "#/$defs/EconomicActivity"
          }
        },
        "informedRevenue": {
          "$ref": "#/$defs/InformedRevenue"
        }
      }
    },
    "financialRelationships": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "startDate",
        "productsServicesType",
        "procurators"
      ],
      "properties": {
        "startDate": {
          "type": "string",
          "format": "date-time",
          "description": "Date when the relationship with the institution started"
        },
        "productsServicesType": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of products and services that the client consumes"
        },
        "productsServicesTypeAdditionalInfo": {
          "type": "string",
          "description": "Additional info about the products and services. Populated when productsServicesType includes 'OUTROS'"
        },
        "procurators": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "type",
              "cpfNumber",
              "civilName"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "REPRESENTANTE_LEGAL",
                  "PROCURADOR"
                ],
                "description": "Type of relationship with the client. Legal representative — natural person who represents the entity and is named in its incorporation document. Procurator — any person authorized in writing to represent the client in some business"
              },
              "cpfNumber": {
                "type": "string",
                "description": "CPF of the procurator. For business links this field may hold a CPF or a CNPJ (kept for backward compatibility — prefer documentNumber + documentType)"
              },
              "documentNumber": {
                "type": "string",
                "description": "Document number of the procurator (CPF or CNPJ). Mirrors cpfNumber and is the canonical value to read"
              },
              "documentType": {
                "type": "string",
                "enum": [
                  "CPF",
                  "CNPJ"
                ],
                "description": "Type of document carried by documentNumber"
              },
              "civilName": {
                "type": "string",
                "description": "Civil name of the procurator. For business procurators, may hold the company name"
              },
              "socialName": {
                "type": "string",
                "description": "Social name of the procurator, if any"
              }
            }
          },
          "description": "List of procurators of the client"
        },
        "accounts": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "compeCode",
              "branchCode",
              "number",
              "checkDigit",
              "type",
              "subtype"
            ],
            "properties": {
              "compeCode": {
                "type": "string",
                "description": "COMPE code of the account"
              },
              "branchCode": {
                "type": "string",
                "description": "Branch code of the account"
              },
              "number": {
                "type": "string",
                "description": "Number of the account"
              },
              "checkDigit": {
                "type": "string",
                "description": "Check digit of the account"
              },
              "type": {
                "type": "string",
                "description": "Type of the account"
              },
              "subtype": {
                "type": "string",
                "description": "Subtype of the account"
              }
            }
          },
          "description": "List of accounts of the client with valid consent. Only accounts that have explicit user consent are returned."
        },
        "portabilitiesReceived": {
          "type": "array",
          "description": "Salary portabilities received by the institution from the client's previous paycheck banks (banco-folha). PF-only field",
          "items": {
            "$ref": "#/$defs/PortabilityReceived"
          }
        },
        "paychecksBankLink": {
          "type": "array",
          "description": "Paycheck-bank (banco-folha) links to employers, active or formerly active. PF-only field",
          "items": {
            "$ref": "#/$defs/PaycheckBankLink"
          }
        }
      },
      "description": "Information that allows institutions to assess, evaluate, characterize, and classify the client with the purpose of understanding their risk profile and their economic-financial capacity"
    },
    "socialName": {
      "type": [
        "string",
        "null"
      ],
      "description": "Social name of the natural person, if any (the name by which travestis and transsexuals recognize themselves and are recognized in their community). PF-only field"
    },
    "sex": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "FEMALE",
        "MALE",
        "OTHER",
        null
      ],
      "description": "Sex of the natural person. PF-only field"
    },
    "maritalStatus": {
      "description": "Marital status of the natural person. PF-only field",
      "anyOf": [
        {
          "$ref": "#/$defs/MaritalStatus"
        },
        {
          "type": "null"
        }
      ]
    },
    "nationality": {
      "description": "Nationality of the natural person. PF-only field",
      "anyOf": [
        {
          "$ref": "#/$defs/Nationality"
        },
        {
          "type": "null"
        }
      ]
    },
    "otherDocuments": {
      "type": [
        "array",
        "null"
      ],
      "description": "List of other identification documents the natural person holds. PF-only field",
      "items": {
        "$ref": "#/$defs/OtherDocument"
      }
    },
    "passport": {
      "description": "Passport metadata for the natural person. PF-only field",
      "anyOf": [
        {
          "$ref": "#/$defs/Passport"
        },
        {
          "type": "null"
        }
      ]
    },
    "incorporationDate": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Date the business was incorporated. PJ-only field"
    },
    "parties": {
      "type": [
        "array",
        "null"
      ],
      "description": "Partners and administrators of the business. PJ-only field",
      "items": {
        "$ref": "#/$defs/BusinessParty"
      }
    },
    "businessOtherDocuments": {
      "type": [
        "array",
        "null"
      ],
      "description": "List of additional documents for businesses headquartered abroad and not required to register a CNPJ. PJ-only field",
      "items": {
        "$ref": "#/$defs/BusinessOtherDocument"
      }
    },
    "companiesCnpj": {
      "type": [
        "array",
        "null"
      ],
      "description": "CNPJs of the financial institutions responsible for the customer cadastro. Numbers only, no mask",
      "items": {
        "type": "string"
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Date when the identity was first ingested by Pluggy."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Date of the last update of the identity data."
    }
  },
  "type": "object",
  "required": [
    "id",
    "itemId"
  ],
  "$defs": {
    "Address": {
      "description": "The address object contains data related to an specific owner's location.",
      "properties": {
        "fullAddress": {
          "type": "string",
          "description": "Full address using all components available"
        },
        "primaryAddress": {
          "type": "string",
          "description": "Primary address, stret name and street number"
        },
        "city": {
          "type": "string",
          "description": "The complete city name"
        },
        "postalCode": {
          "type": "string",
          "description": "The Zip code"
        },
        "state": {
          "type": "string",
          "description": "The state or province"
        },
        "country": {
          "type": "string",
          "description": "The complete country name (free text)"
        },
        "type": {
          "enum": [
            "Personal",
            "Work"
          ],
          "type": "string",
          "description": "Type of address, Personal or Work"
        },
        "additionalInfo": {
          "type": "string",
          "description": "Additional address information such as apartment number, complement, or other details"
        },
        "district": {
          "type": "string",
          "description": "District / neighborhood (bairro) — a community or region within a city or municipality based on geographic subdivisions"
        },
        "ibgeTownCode": {
          "type": "string",
          "description": "IBGE municipality code (7 digits). The IBGE table associates each Brazilian municipality with a 7-digit code; the first two digits identify the Federation Unit"
        },
        "countryCode": {
          "type": "string",
          "description": "Country code in alpha3 ISO-3166 format (e.g. 'BRA')"
        },
        "geographicCoordinates": {
          "$ref": "#/$defs/GeographicCoordinates"
        }
      },
      "type": "object"
    },
    "BusinessOtherDocument": {
      "description": "Additional document for businesses headquartered abroad and not required to register a CNPJ",
      "type": "object",
      "required": [
        "type",
        "number",
        "country"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of the document (e.g. 'EIN')"
        },
        "number": {
          "type": "string",
          "description": "Document number"
        },
        "country": {
          "type": "string",
          "description": "Issuing country in alpha3 ISO-3166 format"
        },
        "expirationDate": {
          "type": "string",
          "format": "date-time",
          "description": "Expiration date of the document"
        }
      }
    },
    "BusinessParty": {
      "description": "Partner or administrator of a business. Partners with less than 25% shareholding may be omitted by the institution",
      "type": "object",
      "required": [
        "type",
        "personType",
        "documentType",
        "documentNumber"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "PARTNER",
            "ADMINISTRATOR"
          ],
          "description": "Role of the party in the business. Administrator — runs the day-to-day, signs documents and legally responds for the entity. Partner — holds capital but may not be involved in administrative activities"
        },
        "personType": {
          "type": "string",
          "enum": [
            "NATURAL_PERSON",
            "LEGAL_ENTITY"
          ],
          "description": "Whether the party is a natural person or a legal entity"
        },
        "documentType": {
          "type": "string",
          "enum": [
            "CPF",
            "CNPJ",
            "PASSPORT",
            "OTHER_TRAVEL_DOCUMENT"
          ],
          "description": "Type of the party's identification document"
        },
        "documentNumber": {
          "type": "string",
          "description": "Number of the identification document (digits and check digit, if any)"
        },
        "documentCountry": {
          "type": "string",
          "description": "Issuing country of the document, alpha3 ISO-3166"
        },
        "documentExpirationDate": {
          "type": "string",
          "format": "date-time",
          "description": "Expiration date of the document"
        },
        "documentIssueDate": {
          "type": "string",
          "format": "date-time",
          "description": "Issue date of the document"
        },
        "documentAdditionalInfo": {
          "type": "string",
          "description": "Free-text complement when the document carries identification info that doesn't fit the other fields"
        },
        "civilName": {
          "type": "string",
          "description": "Civil name of the party. Required when personType is NATURAL_PERSON"
        },
        "socialName": {
          "type": "string",
          "description": "Social name of the natural-person party, if any"
        },
        "companyName": {
          "type": "string",
          "description": "Company name of the party. Required when personType is LEGAL_ENTITY"
        },
        "tradeName": {
          "type": "string",
          "description": "Trade name of the legal-entity party, if any"
        },
        "startDate": {
          "type": "string",
          "format": "date-time",
          "description": "Date the party's participation started"
        },
        "shareholding": {
          "type": "number",
          "description": "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"
        }
      }
    },
    "EconomicActivity": {
      "description": "CNAE code describing one of the business's economic activities. Only one entry per response should be marked as main",
      "type": "object",
      "required": [
        "code",
        "isMain"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "CNAE code (7 digits, including leading zeros). Follows the CNAE-Subclasse 2.3 classification"
        },
        "isMain": {
          "type": "boolean",
          "description": "Whether this is the main economic activity (true) or a secondary one (false). Only one item per response should be true"
        }
      }
    },
    "Email": {
      "description": "The email object contains emails associated with the owner of the account",
      "properties": {
        "type": {
          "enum": [
            "Personal",
            "Work"
          ],
          "type": "string",
          "description": ""
        },
        "value": {
          "type": "string",
          "description": "The full email of the person."
        }
      },
      "type": "object",
      "required": [
        "value"
      ]
    },
    "GeographicCoordinates": {
      "description": "Geographic coordinates in decimal degrees, WGS84 reference system",
      "type": "object",
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "description": "Latitude. Between -90 and 90 (e.g. -23.5475)"
        },
        "longitude": {
          "type": "number",
          "description": "Longitude. Between -180 and 180 (e.g. -46.6361)"
        }
      }
    },
    "IdentityRelation": {
      "description": "The relation object contains name and relation to the owner of the account",
      "properties": {
        "type": {
          "enum": [
            "Mother",
            "Father",
            "Spouse"
          ],
          "type": "string",
          "description": "Type of relation: Father, Mother or Spouse"
        },
        "name": {
          "type": "string",
          "description": "The full name of the person"
        },
        "document": {
          "type": "string",
          "description": "Primary document of the person"
        }
      },
      "type": "object"
    },
    "InformedRevenue": {
      "description": "Revenue (faturamento) informed by the business — the business equivalent of informedIncome",
      "type": "object",
      "required": [
        "amount"
      ],
      "properties": {
        "amount": {
          "type": "number",
          "description": "Amount of the informed revenue"
        },
        "frequency": {
          "type": "string",
          "enum": [
            "DAILY",
            "WEEKLY",
            "BIWEEKLY",
            "MONTHLY",
            "BIMONTHLY",
            "QUARTERLY",
            "SEMIANNUAL",
            "ANNUAL",
            "OTHER"
          ],
          "description": "Frequency or period of the informed revenue"
        },
        "frequencyAdditionalInfo": {
          "type": "string",
          "description": "Free-text complement to the frequency. Populated when frequency is OTHER"
        },
        "year": {
          "type": "number",
          "description": "Reference year of the revenue"
        }
      }
    },
    "MaritalStatus": {
      "description": "Marital status of the natural person",
      "type": "object",
      "required": [
        "code"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "SINGLE",
            "MARRIED",
            "WIDOWED",
            "JUDICIALLY_SEPARATED",
            "DIVORCED",
            "STABLE_UNION",
            "OTHER"
          ],
          "description": "Marital status code"
        },
        "additionalInfo": {
          "type": "string",
          "description": "Free-text complement. Populated when code is OTHER"
        }
      }
    },
    "Nationality": {
      "description": "Nationality of the natural person",
      "type": "object",
      "required": [
        "hasBrazilianNationality"
      ],
      "properties": {
        "hasBrazilianNationality": {
          "type": "boolean",
          "description": "Whether the client has Brazilian nationality"
        },
        "otherNationalities": {
          "type": "array",
          "description": "Other nationalities held by the client, if any",
          "items": {
            "type": "object",
            "required": [
              "countryCode",
              "documents"
            ],
            "properties": {
              "countryCode": {
                "type": "string",
                "description": "Country code in alpha3 ISO-3166 format"
              },
              "documents": {
                "type": "array",
                "description": "Supporting documents for this nationality",
                "items": {
                  "$ref": "#/$defs/NationalityDocument"
                }
              }
            }
          }
        }
      }
    },
    "NationalityDocument": {
      "description": "Supporting document for a non-Brazilian nationality",
      "type": "object",
      "required": [
        "type",
        "number"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Document type (free text). Required when the nationality is not Brazilian"
        },
        "number": {
          "type": "string",
          "description": "Document number. Required when the nationality is not Brazilian"
        },
        "country": {
          "type": "string",
          "description": "Country name"
        },
        "issueDate": {
          "type": "string",
          "format": "date-time",
          "description": "Issue date of the document"
        },
        "expirationDate": {
          "type": "string",
          "format": "date-time",
          "description": "Expiration date of the document"
        },
        "additionalInfo": {
          "type": "string",
          "description": "Free-text complement"
        }
      }
    },
    "OtherDocument": {
      "description": "Other identification document held by the natural person. Brazilian acronyms are kept verbatim; OTHER covers any other type",
      "type": "object",
      "required": [
        "type",
        "number"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "CNH",
            "RG",
            "NIF",
            "RNE",
            "OTHER"
          ],
          "description": "Document type"
        },
        "typeAdditionalInfo": {
          "type": "string",
          "description": "Free-text complement. Populated when type is OTHER"
        },
        "number": {
          "type": "string",
          "description": "Document number"
        },
        "checkDigit": {
          "type": "string",
          "description": "Check digit of the document, if it has one"
        },
        "additionalInfo": {
          "type": "string",
          "description": "Free-text complement, used to record the issuing authority (e.g. 'SSP/SP') when relevant"
        },
        "expirationDate": {
          "type": "string",
          "format": "date-time",
          "description": "Expiration date of the document"
        }
      }
    },
    "Passport": {
      "description": "Passport metadata for the natural person. Applies when the client is a non-resident not required to register a CPF",
      "type": "object",
      "required": [
        "number",
        "country"
      ],
      "properties": {
        "number": {
          "type": "string",
          "description": "Passport number"
        },
        "country": {
          "type": "string",
          "description": "Issuing country in alpha3 ISO-3166 format"
        },
        "issueDate": {
          "type": "string",
          "format": "date-time",
          "description": "Issue date of the passport"
        },
        "expirationDate": {
          "type": "string",
          "format": "date-time",
          "description": "Expiration date of the passport"
        }
      }
    },
    "PaycheckBankLink": {
      "description": "Paycheck-bank (banco-folha) link to an employer, active or formerly active. Old employers may not have closed the link, so an entry doesn't guarantee the listed employer is the current one",
      "type": "object",
      "required": [
        "employerName",
        "employerDocument",
        "paycheckBankCnpj",
        "paycheckBankIspb",
        "accountOpeningDate"
      ],
      "properties": {
        "employerName": {
          "type": "string",
          "description": "Employer name as registered when the paycheck account was opened. When the employer is a legal entity, this is the company name"
        },
        "employerDocument": {
          "type": "string",
          "description": "Employer document (CPF or CNPJ) as registered when the paycheck account was opened"
        },
        "paycheckBankCnpj": {
          "type": "string",
          "description": "CNPJ of the institution contracted to provide the paycheck service (banco-folha)"
        },
        "paycheckBankIspb": {
          "type": "string",
          "description": "ISPB of the institution contracted to provide the paycheck service"
        },
        "accountOpeningDate": {
          "type": "string",
          "format": "date-time",
          "description": "Date the paycheck account was opened"
        }
      }
    },
    "PhoneNumber": {
      "description": "The phone number object contains data related to contact information.",
      "properties": {
        "type": {
          "enum": [
            "Personal",
            "Work",
            "Residencial"
          ],
          "type": "string",
          "description": "Type of phone number: personal, work or residencial"
        },
        "value": {
          "type": "string",
          "description": "The complete phone number"
        },
        "countryCallingCode": {
          "type": "string",
          "description": "International dialing code (DDI). Populated when different from '55'"
        },
        "areaCode": {
          "type": "string",
          "description": "Area code (DDD) of the client's phone"
        },
        "extension": {
          "type": "string",
          "description": "Extension number, when part of the phone identification"
        },
        "additionalInfo": {
          "type": "string",
          "description": "Additional info related to the source phone type. Populated when the source type at the institution does not fit the standard categories"
        }
      },
      "type": "object",
      "required": [
        "value"
      ]
    },
    "PortabilityReceived": {
      "description": "Salary portability received by the institution from a previous paycheck bank (banco-folha). Approved requests only — a portability is never explicitly closed, so an entry doesn't guarantee an active link with the listed paycheck bank",
      "type": "object",
      "required": [
        "employerName",
        "employerDocument",
        "paycheckBankDetainerCnpj",
        "paycheckBankDetainerIspb",
        "portabilityApprovalDate"
      ],
      "properties": {
        "employerName": {
          "type": "string",
          "description": "Employer name as received in the portability message. When the employer is a legal entity, this is the company name"
        },
        "employerDocument": {
          "type": "string",
          "description": "Employer document (CPF or CNPJ) as received in the portability message"
        },
        "paycheckBankDetainerCnpj": {
          "type": "string",
          "description": "CNPJ of the bank that holds the paycheck account (banco-folha) as received in the portability message"
        },
        "paycheckBankDetainerIspb": {
          "type": "string",
          "description": "ISPB of the bank that holds the paycheck account as received in the portability message"
        },
        "portabilityApprovalDate": {
          "type": "string",
          "format": "date-time",
          "description": "Date the portability was approved"
        }
      }
    }
  }
}