Complete claim

Completes a confirmed claim, finalizing the key transfer.

POST /api/v1/dict/claims/{claimID}/complete

Complete claim

cURL

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/claims/{claimID}/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "requestId": "b2696bf1-0a51-48b0-ab4a-8af2dff440af"
}
'

200

{
  "claimType": "OWNERSHIP",
  "claimerISPB": "12345678",
  "deadline": "2025-03-14T14:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "keyType": "PHONE",
  "keyValue": "[phone]",
  "status": "OPEN",
  "bacen": {
    "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "lastModified": "2026-06-14T12:00:00Z",
    "responseTime": "2026-06-14T12:00:00Z"
  },
  "bacenClaimId": "550e8400-e29b-41d4-a716-446655440111",
  "cancelReason": "USER_REQUESTED",
  "cancelledBy": "DONOR",
  "claimerAccountNumber": "9988776",
  "claimerAccountType": "CACC",
  "claimerBranch": "0001",
  "claimerName": "João Silva",
  "claimerOpeningDate": "2020-01-15T00:00:00Z",
  "claimerTaxId": "11122233300",
  "claimerTradeName": "Silva ME",
  "claimerType": "NATURAL_PERSON",
  "completionPeriodEnd": "2025-03-21T14:30:00Z",
  "confirmReason": "USER_REQUESTED",
  "donorISPB": "87654321",
  "lastModified": "2025-03-07T14:30:00Z",
  "requestedAt": "2025-03-07T14:30:00Z",
  "resolution": "",
  "resolutionPeriodEnd": "2025-03-14T14:30:00Z",
  "resolvedAt": ""
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Idempotency key, max 255 characters

Path Parameters

claimID · string<uuid> · required

Claim UUID

Body

application/json

Completion request identifier. The completing claimer is derived from the authenticated participant, not this body.

requestId · string<uuid> · required

Idempotency key for this completion, a version 4 UUID, sent verbatim to BACEN as completeClaim's RequestId. Required — never invented here. Must be version 4: every other version derives from a clock, a node id or a hashed name, so two different completions can collide by construction. Distinct from the X-Idempotency header, which is this rail's own de-duplication and never reaches BACEN.

Example:

"b2696bf1-0a51-48b0-ab4a-8af2dff440af"

Response

200

application/json

OK

Claim record with its current status and deadlines

claimType · string · required

Claim kind: OWNERSHIP or PORTABILITY

Example:

"OWNERSHIP"

claimerISPB · string · required

ISPB (8 numeric digits) of the participant initiating the claim

Example:

"12345678"

deadline · string · required

Donor-response deadline (RFC 3339, UTC). For a claim BACEN's own record backs (discovered or adopted), this IS BACEN's ExtendedClaim.ResolutionPeriodEnd, same value as resolutionPeriodEnd below. For a locally-initiated claim, this is always a local seven-day-from-initiation estimate that drives the deadline sweep — see resolutionPeriodEnd for BACEN's own authoritative value, populated once the initiation outbox handler decodes BACEN's createClaim response.

Example:

"2025-03-14T14:30:00Z"

id · string · required

Server-assigned claim UUID

Example:

"550e8400-e29b-41d4-a716-446655440000"

keyType · string · required

PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP

Example:

"PHONE"

keyValue · string · required

PIX key value under claim

Example:

"[phone]"

status · string · required

Claim lifecycle state: OPEN, WAITING_RESOLUTION, CONFIRMED, CANCELLED, or COMPLETED

Example:

"OPEN"

bacen · object

BACEN's own operational envelope for its most recent interaction on this claim; omitted when no BACEN interaction has ever landed on it.

Show child attributes

bacenClaimId · string

The id BACEN itself assigned to this claim on createClaim (ExtendedClaim.Id) — the address every BACEN-facing verb and both claim-recovery feeds use internally. Read-only, surfaced so an operator can correlate a BACEN support case or a DICT-side rejection back to this claim. Omitted until BACEN's createClaim response has landed: a locally initiated claim whose initiation outbox handler has not yet processed BACEN's reply carries no value here yet.

Example:

"550e8400-e29b-41d4-a716-446655440111"

cancelReason · enum<string>

Matches BACEN's ExtendedClaim.CancelReason vocabulary plus COURT_ORDER: the reason the claim was cancelled, once cancelled. On a claim we cancel ourselves (our own cancel verb) this is the reason our own operator submitted; on a claim discovered or adopted from BACEN's directory it is BACEN's own published value, verbatim. COURT_ORDER is the one value BACEN does not define at the pinned DICT 2.12.1: it is recorded locally on a court-ordered cancellation, and that cancellation reaches BACEN carrying USER_REQUESTED until the DICT reaches 2.13, which adds the value to ClaimOperationReason

Available options: USER_REQUESTED, ACCOUNT_CLOSURE, FRAUD, DEFAULT_OPERATION, RECONCILIATION, RFB_VALIDATION, PARTICIPANT_EXCLUSION, COURT_ORDER

cancelledBy · enum<string>

Matches BACEN's ExtendedClaim.CancelledBy vocabulary: the side that cancelled the claim, once cancelled. On a claim we cancel ourselves this is the side derived from the authenticated caller; on a claim discovered or adopted from BACEN's directory it is BACEN's own published value, verbatim

Available options: DONOR, CLAIMER

claimerAccountNumber · string

Number of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.AccountNumber). Answered on every claim projection, the list included

Example:

"9988776"

claimerAccountType · enum<string>

Type of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.AccountType). Answered on every claim projection, the list included

Available options: CACC, SVGS, TRAN, SLRY, OTHR

Example:

"CACC"

claimerBranch · string

Branch of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.Branch); optional at BACEN, so empty when the claimer lodged none. Answered on every claim projection, the list included

Example:

"0001"

claimerName · string

Name of the claiming key owner (ExtendedClaim.Claimer.Name). Answered on every claim projection, the list included; not carried on a claim streaming fact

Example:

"João Silva"

claimerOpeningDate · string

Opening date of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.OpeningDate, RFC 3339 UTC). Answered on every claim projection, the list included

Example:

"2020-01-15T00:00:00Z"

claimerTaxId · string

CPF/CNPJ of the claiming key owner (ExtendedClaim.Claimer.TaxIdNumber). Answered on every claim projection, the list included; not carried on a claim streaming fact

Example:

"11122233300"

claimerTradeName · string

Trade name of the claiming key owner (ExtendedClaim.Claimer.TradeName); legal-entity claimers only, empty for a natural person. Answered on every claim projection, the list included

Example:

"Silva ME"

claimerType · enum<string>

BACEN's Person discriminator for the claiming key owner (ExtendedClaim.Claimer.Type). DERIVED from the tax id's length, never stored: 11 characters is the CPF branch, 14 the CNPJ branch — the same rule BACEN's own oneOf keys on. Empty when the tax id is absent or has no branch. Answered on every claim projection, the list included

Available options: NATURAL_PERSON, LEGAL_PERSON

Example:

"NATURAL_PERSON"

completionPeriodEnd · string

BACEN's own completion-window end for a possession claim (ExtendedClaim.CompletionPeriodEnd, RFC 3339 UTC); BACEN publishes it for OWNERSHIP claims only and omits it for PORTABILITY. Also omitted whenever BACEN has not published this claim yet.

Example:

"2025-03-21T14:30:00Z"

confirmReason · enum<string>

Matches BACEN's ExtendedClaim.ConfirmReason vocabulary: the reason the donor confirmed with, once confirmed — unlike resolution this is NOT terminal-gated and is never cleared by a later transition. On a claim we confirm ourselves (our own respond verb) this is the reason our own operator submitted; on a claim discovered or adopted from BACEN's directory it is BACEN's own published value, verbatim

Available options: USER_REQUESTED, ACCOUNT_CLOSURE, FRAUD, DEFAULT_OPERATION, RECONCILIATION, RFB_VALIDATION, PARTICIPANT_EXCLUSION

donorISPB · string

ISPB (8 numeric digits) of the current key owner (donor). It is the DICT that resolves the donor, not this rail: a claim lodged on a key held at another institution — the canonical portability case — carries NO donor until BACEN's createClaim response names one (ExtendedClaim.DonorParticipant), so this field is omitted while the donor is pending. A donor-side claim discovered from BACEN's directory always carries it.

Example:

"87654321"

lastModified · string

BACEN's own last-transition instant for this claim (ExtendedClaim.LastModified, RFC 3339 UTC) — the version discriminator BACEN publishes, distinct from requestedAt (when WE lodged it) and from resolvedAt (when it ended). Present once BACEN's own record for this claim exists; omitted before that.

Example:

"2025-03-07T14:30:00Z"

requestedAt · string

Claim initiation timestamp (RFC 3339, UTC); omitted for a donor-side claim projected from BACEN, whose ExtendedClaim carries no creation time

Example:

"2025-03-07T14:30:00Z"

resolution · string

Terminal resolution reason (e.g. CANCELLED_BY_CLAIMER, CANCELLED_BY_CLAIMER_FRAUD, CANCELLED_BY_DONOR, CANCELLED_BY_DONOR_FRAUD, DEADLINE_EXPIRED, AUTO_COMPLETED, TRANSFER_COMPLETED); empty until the claim resolves — CONFIRMED is not terminal and never sets this field

Example:

""

resolutionPeriodEnd · string

BACEN's own resolution-window end for this claim (ExtendedClaim.ResolutionPeriodEnd, RFC 3339 UTC); present once BACEN's own record for this claim exists — discovered, adopted, or a locally-initiated claim whose createClaim response the initiation outbox handler has processed — omitted before that

Example:

"2025-03-14T14:30:00Z"

resolvedAt · string

Resolution timestamp (RFC 3339, UTC); omitted while the claim is unresolved

Example:

""