Get a PIX key claim

Reads one claim live from DICT (§8.2.15 Consultar Reivindicação). Nothing local is consulted: account_id exists only to validate the caller and to produce the ISPB §8.2.15 requires, and the plugin’s own key row is deliberately ignored because it is absent for a claim this plugin never opened and gone once the row is soft-deleted.

This route serves the same universe as the default GET /v1/claims: the claims of the caller’s ACCOUNT, by the same rule (a claim the account opened is also recognised by its own account block - account number, and branch, account type and holder document when DICT sends them - with the caller’s ISPB, whatever participation flow DICT states). A claim of another account of the same institution is 404 PIX-0020, exactly like a claim DICT does not know. The response carries claimId, key and ispb plus the optional claim facts - claimType, claimSituation (DICT’s raw stReivindicacao: 0 open, 1 awaiting resolution, 2 confirmed, 3 cancelled, 4 completed), claimSide, claimerIspb, donorIspb, resolutionDeadline and conclusionDeadline - so it says whether the claim is open, confirmed or ended and which side you answer it from. A claimId DICT does not know is 404 PIX-0020, and DICT being unavailable is 503 PIX-1050.

Which participant’s DICT mailbox is read is decided by ispb, by exactly the rule an order’s payerIspb follows - and here it decides WHOSE claims come back, not merely which credential signs the call, because §8.2.13 and §8.2.15 answer for a PARTICIPANT. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it.

GET /v1/claims/{claimId}

Get a PIX key claim

cURL

curl --request GET \
  --url https://api.example.com/v1/claims/{claimId} \
  --header 'Authorization: Bearer <token>'

200

{
  "claimId": "claim-123",
  "ispb": "12345678",
  "key": "11122233300",
  "claimSide": "donor",
  "claimSituation": 1,
  "claimType": 0,
  "claimerIspb": "17826860",
  "conclusionDeadline": "2026-10-31T20:00:00.000Z",
  "donorIspb": "88000001",
  "resolutionDeadline": "2026-10-30T20:22:10.008Z"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Path Parameters

claimId · string · required

The claim id.

Example:

"claim-123"

Query Parameters

account_id · string · required

The Midaz ledger account id of the caller.

Example:

"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b"

ispb · string

The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it.

Pattern: ^[0-9A-Z]{8}$

Example:

"12345678"

Response

200

application/json

OK

claimId · string · required

The claim id.

Example:

"claim-123"

ispb · string · required

The claim requester ISPB.

Example:

"12345678"

key · string · required

The claimed PIX key.

Example:

"11122233300"

claimSide · string

The side this account acts on in the claim: claimer (it asked for the key) or donor (it holds the key and is asked to give it away).

Example:

"donor"

claimSituation · integer<int64>

JDPI stReivindicacao of the claim: 0=Open (not yet read by the donor), 1=Awaiting resolution (read by the donor), 2=Confirmed by the donor, 3=Cancelled, 4=Completed. Omitted when the source states none (a key the directory marks as under claim).

Example:

1

claimType · integer<int64>

JDPI tpReivindicacao of the claim: 0=portability (same holder, another participant), 1=possession (another holder). Omitted when there is no claim.

Example:

0

claimerIspb · string

ISPB of the participant that opened the claim (the claimer).

Example:

"17826860"

conclusionDeadline · string

JDPI dtHrLimiteConclusao: by when the claimer must conclude a confirmed claim (UTC). Until then the donor may still cancel a confirmed possession claim for fraud.

Example:

"2026-10-31T20:00:00.000Z"

donorIspb · string

ISPB of the participant that holds the key today (the donor).

Example:

"88000001"

resolutionDeadline · string

JDPI dtHrLimiteResolucao: by when the donor must confirm or refuse the claim (UTC, aaaa-mm-ddTHH:mm:ss.sssZ).

Example:

"2026-10-30T20:22:10.008Z"