Open a PIX key claim

Opens a DICT claim (reivindicação) on a PIX key that another participant currently holds. You are the CLAIMER - the Cliente Reivindicador of §8.2.07 - and the body carries only key and accountId, because the claim TYPE is not yours to choose: the service decides it, portability when the key’s holder document at DICT equals your account document and possession otherwise, which is the rule §8.2.07 states.

The precondition the body does not show is the one that fails most often. The key must ALREADY sit on this account as a claim-pending row (status 4), and the only thing that creates one is POST /v1/entries answering that DICT recognised the key as claimable. Claiming a key you never tried to register is 422 PIX-0073. For a CPF or CNPJ key your account document must equal the key value, else 422 PIX-0086. The call is idempotent: a row already carrying a claim id returns that claim instead of opening a second one.

On success the row moves to status 5 - waiting for the holder to hand the key over. §8.2.07 gives the holder a deadline to read the claim and then a further deadline to accept or refuse it; this service neither enforces nor exposes those windows, so track the outcome with GET /v1/claims?status=processing or GET /v1/entries. Per §8.2.07 an EVP (RANDOM) key cannot be claimed at all - mint a new one instead.

POST /v1/claims

Open a PIX key claim

cURL

curl --request POST \
  --url https://api.example.com/v1/claims \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "key": "11122233300"
}
'

201

{
  "status": 5,
  "type": 0,
  "claimId": "claim-123",
  "key": "11122233300",
  "statusDescription": "CLAIMER_PENDING_OWNER_GIVEAWAY"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Body

application/json

accountId · string · required

The CRM account id of the claimer.

Example:

"acc-123"

key · string · required

The PIX key to claim.

Example:

"11122233300"

Response

201

application/json

Created

status · integer<int64> · required

Numeric eKeyStatus.

Example:

5

type · integer<int64> · required

Numeric eKeyType.

Example:

0

claimId · string

The created/associated claim id.

Example:

"claim-123"

key · string

The PIX key value.

Example:

"11122233300"

statusDescription · string

Human-readable eKeyStatus label.

Example:

"CLAIMER_PENDING_OWNER_GIVEAWAY"