Endpoint
POST /v3/pix_keys/create
Authentication and target
Use an account credential for its bound account, or a user credential with bothX-ISPB and X-Account-Number. If an account credential sends those headers, both must be present and must match its bound account. Platform credentials are not accepted. All requests require the standard HMAC-SHA256 headers.
The curl example below uses an ACCOUNT credential bound to the operated account, so it omits X-ISPB and X-Account-Number. If X-Client-ID identifies a USER credential, add both target headers and include their exact trimmed values in the canonical header set before calculating X-Signature.
Request body
pix_key_type is required and numeric: 1 CPF, 2 CNPJ, 3 EMAIL, 4 PHONE, 5 EVP. pix_key_value is required except for EVP. CNPJ normalization trims the value and uppercases a recognized alphanumeric form; downstream DICT/provider validation remains authoritative.
Success data
pix_key, numeric pix_key_type, numeric status, and numeric created_at.
Behavior and validation
If DICT omitscreated_at, the service supplies the current Unix-millisecond time. This endpoint exposes no idempotency key.
Errors
Every call can fail for missing or invalid signature headers, an expired timestamp, nonce replay, an invalid body hash or signature, insufficient permission, or a downstream service error. Endpoint-specific errors include:4000missing type or required value;500missing account context.501DICT failure plus mapped PIX-key errors, including already-linked or inactive conditions.