Skip to navigation

Account holder details

The account address is the holder’s address at the settlement bank. A person changes it right away. A company opens a request, and the desk only saves it after the proof.

Read

GET /v1/accounts/{accountId}/holder returns the live name, document and address. The response carries Cache-Control: no-store. Scope holder.read.

Person

PUT /v1/accounts/{accountId}/holder/address works only when the account document is a CPF and X-Acting-Document is that same CPF. The cityIbgeCode must match the state. It moves no money and takes no Idempotency-Key.

A company account on this route answers 422 holder_update_required.

Company

POST /v1/accounts/{accountId}/holder-updates with Idempotency-Key.

kindrequired document
addresscompany_proof_of_address
registrationcompany_articles (CNPJ, partner document and others are optional)

The file goes up through the signed URL (evidence/upload-url and evidence/add): PDF, JPEG or PNG up to 5 MB. submit only counts files with scanStatus APPROVED. Approving an address request is what calls the settlement bank; if the bank refuses, the request stays under review.

A request waiting for documents for 7 days is cancelled (holder_update.updated with reason=expired).

The webhook does not carry the address. Read the GET again.