Include PIX Key Claim

Time	Status	User Agent
Retrieving recent requests…

Endpoint

POST /v3/dict/claim

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC).	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Body Details

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678",
  "type": "CELL_PHONE",
  "verification_request_id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "123456"
}

Field	Type	Description	Required or Optional
source_account_branch_identifier	String	Branch identifier of the source account	required
source_account_number	String	Account number of the source account	required
type	String	PIX key type. Valid values: CPF, CNPJ, CELL_PHONE, EMAIL (EVP not allowed for claims)	required
verification_request_id	String	Verification request ID (required for EMAIL and CELL_PHONE key types). Must be obtained from the verification endpoint first	required for EMAIL and CELL_PHONE
token	String	Verification token. For EMAIL/CELL_PHONE: OTP code (required). For CPF/CNPJ: not required (HMAC authentication is used instead)	required for EMAIL and CELL_PHONE

Request Examples

Portability claim with phone number:

POST /v3/dict/claim
Authorization: Bearer access_token_here
hmac: computed_hmac_signature
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678",
  "type": "CELL_PHONE",
  "verification_request_id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "123456"
}

Ownership claim with CPF:

POST /v3/dict/claim
Authorization: Bearer access_token_here
hmac: computed_hmac_signature
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678",
  "type": "CPF"
}

Portability claim with email:

POST /v3/dict/claim
Authorization: Bearer access_token_here
hmac: computed_hmac_signature
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678",
  "type": "EMAIL",
  "verification_request_id": "6b3e2bc7-9a12-4c8e-bf72-335aa814d091",
  "token": "789012"
}

Response Details

{
  "worked": true,
  "pix_key_claim_id": "abc123def456ghi789",
  "claim_id": "123e4567-e89b-12d3-a456-426655440000",
  "type": "CELL_PHONE",
  "key": "+5511999999999",
  "claim_type": "PORTABILITY",
  "status": "OPEN",
  "resolution_deadline": "2024-12-31T23:59:59.999Z",
  "conclusion_deadline": "2025-01-02T23:59:59.999Z",
  "created_at": "2024-12-24T10:30:00.000Z",
  "message": "Claim opened successfully in the DICT."
}

Field	Type	Description
worked	Boolean	Always `true` for successful requests.
pix_key_claim_id	String	Internal database ID for this claim record
claim_id	String	DICT claim identifier (UUID format)
type	String	PIX key type being claimed
key	String	The PIX key value being claimed
claim_type	String	Type of claim: `PORTABILITY` or `OWNERSHIP`
status	String	Current claim status. Initially `OPEN`
resolution_deadline	String	Deadline for donor to respond (ISO 8601 format). Typically 7 days from creation
conclusion_deadline	String	Deadline for claimer to conclude (ownership claims only). Typically 2 days after confirmation
created_at	String	Timestamp when the claim was created (ISO 8601 format)
message	String	Informative message about the operation result

Error Responses

HTTP Code	Error Message	Description
400	Invalid key type	The key type provided is invalid or not supported for claims (e.g., EVP)
400	Verification required	Verification request ID and token are required for EMAIL and CELL_PHONE keys
400	HMAC header required	HMAC authentication header is missing
400	Company not found	The company associated with the authenticated user was not found
400	Account not found	The source account was not found or is not active
400	AccountBank is closed	The account is closed and cannot be used
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature.
404	Verification request not found	The verification request ID was not found or has expired
422	Validation error	Request validation failed. Check that all required fields are present and in the correct format.

Business Rules

Key Type Restrictions:

EVP (random) keys cannot be claimed - users must create a new random key instead
Email keys can only be used for portability claims, not ownership claims
Phone, CPF, and CNPJ keys support both portability and ownership claims

Verification Requirements:

Email and Phone keys: Must provide verification_request_id and token (OTP code)
- First request verification using the verification endpoint with purpose CLAIM_INCLUSION
- Then include the claim with the verification ID and OTP received
CPF/CNPJ keys: Authentication via HMAC signature only (no token needed)

Claim Type Determination:

System automatically determines if the claim is PORTABILITY or OWNERSHIP based on:
- If the key is registered to the same CPF/CNPJ → PORTABILITY
- If the key is registered to a different CPF/CNPJ → OWNERSHIP

Account Requirements:

Source account must be active and not blocked
You must have access to the specified account

Existing Claims:

Only one active claim per key is allowed
If a claim already exists, the endpoint will return an error

Important Notes:

Portability claims: Donor has 7 days to respond; automatic confirmation if no response
Ownership claims: Donor must explicitly confirm; claimer must then conclude within 2 days
Both claimer and donor can cancel claims while in OPEN or WAITING_RESOLUTION status
Once a claim is confirmed, only the claimer can act (conclude for ownership, or wait for automatic completion for portability)