Consult Pix Key Data at the Central Bank

Request

ENDPOINT

/pix_key/PIX_KEY

METHOD

GET

Request Path Params

Field	Type	Description	Characters
pix_key *	string	Pix Key to be queried.	77

Types of Pix Key

The “pix_key” can be a CPF, CNPJ, Email, Mobile Number, or a Random Key (UUID), following these formats: CPF: Integer number with 11 digits. CNPJ: Integer number with 14 digits. Email: Text containing at least one “@”. Mobile Number: Text containing the following values: “+55” + “Cell Phone Area Code“ + “Cell Phone Number with a minimum of 8 and a maximum of 9 digits”. Example: “+5511987654321“. Random Key: UUID4.

Request Query Params

Field	Type	Description	Characters
account_key *	uuidv4	Unique identification key of the account.	36
document_number	string	CPF/CNPJ of the Pix Key holder. By passing this parameter, the field is_pix_key_owner will be returned with a boolean value indicating whether the CPF/CNPJ provided matches the Pix Key holder's.	14 or 11

Usage of Query Tokens

To charge the Pix key query token from the account holder, it is mandatory to send the account_key. If the account_key is not sent, the token will be charged from the document number of the integrator partner.

Response

STATUS

200

Response Body: Active Key

{
  "account_branch": "452",
  "account_created_at": "2021-10-22T20:30.459Z",
  "account_digit": "1",
  "account_number": "370158",
  "account_type": "checking_account",
  "bank_code": "237",
  "end_to_end_id": "E3240250220230404185631R0kjZnC6G",
  "financial_institution": "BCO BRADESCO S.A.",
  "is_pix_key_owner": false,
  "ispb": "60746948",
  "owner_masked_document_number": "***.141.857-**",
  "owner_name": "Teste teste",
  "owner_person_type": "legal",
  "owner_trading_name": "Teste LTDA.",
  "pix_key": "teste@gmail.com"
}

Field	Type	Description	Max. Characters
account_branch	string	Account branch linked to the Pix Key, without the check digit.	4
account_created_at	string	Account opening date linked to the Pix Key, provided by the custodian institution of the account.	21
account_digit	string	Check digit of the account linked to the Pix Key.	1
account_number	string	Account number linked to the Pix Key without the check digit.	20
account_type	enum	Definition of the account type of the Pix Key.	Enumerators Account Type
bank_code	string	Bank code of the Pix Key registrar. May be null for institutions that do not have a bank code.	3
end_to_end_id	string	Unique identifier of the Pix key query at Bacen. Must be sent in the Pix transfer so that the token consumed in the query can be recovered.	32
financial_institution	string	Name of the financial institution registering the Pix Key.	200
is_pix_key_owner	boolean	A boolean value will be returned if the document_number parameter is passed in the request. This field indicates whether the CPF/CNPJ provided in the document_number parameter matches the Pix Key holder. It will return null if the document_number parameter is not provided.	-
ispb	string	ISPB of the Participant holding the Pix Key.	8
owner_masked_document_number	string	Masked CPF number or CNPJ of the Pix Key holder.	14
owner_name	string	Name of the Pix Key holder.	120
owner_person_type	enum	Legal nature of the Pix Key holder.	Enumerators Owner Person Type
owner_trading_name	string	Trade name of the Pix Key holder (only for owner_person_type=legal).	100
pix_key	string	Pix Key.	-

Enumerators account_type

Enumerator	Description
payment	Conta de pagamento
checking	Conta de corrente
savings	Conta poupança
saving	Conta poupança
salary	Conta salário
saving_account	Conta poupança
payment_account	Conta de pagamento
checking_account	Conta de corrente
salary_account	Conta salário
escrow	Conta Vinculada

info

Different enumerators can mean the same type of account due to the information returned by different institutions.

Enumerators owner_person_type

Enumerator	Description
natural	string
legal	string

STATUS

4XX

Response Body

{
  "title": "titulo",
  "description": "description in English",
  "translation": "description in Portuguese",
  "code": "code"
}

HTTP Code	QI Code code	Title title	Description (eng) Description	Description (ptbr) translation
404	PIX000017	Pix Key Not Found	Pix key {pix_key} not found.	A chave pix {pix_key} não foi encontrada.
403	PIX000080	Not enough permission	The selected agent doesn't have permission to access this resource.	O agente selecionado não tem permissão para acessar este recurso.
429	PIX000081	Rate Limit Exceeded	Rate Limit Exceeded	Limite de requisições excedido
404	PIX000083	Pix Key not found	Pix Key {pix_key} not found for Alias {alias_key}	Chave Pix {pix_key} não encontrada para o Alias {alias_key}
400	PIX000084	Only one query param allowed	Only one query param allowed	Somente um parâmetro de consulta é permitido