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.
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.