Initiate claim

Initiates a new PIX key ownership or portability claim for the participant identified in the route. Claim deadlines are seven calendar days and claimer/donor ISPB equality is rejected by domain validation.

POST /api/v1/dict/participants/{participantISPB}/claims

Initiate claim

cURL

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/participants/{participantISPB}/claims \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "claimType": "OWNERSHIP",
  "claimerAccountNumber": "9988776",
  "claimerAccountType": "CACC",
  "claimerName": "João Silva",
  "claimerOpeningDate": "2020-01-15T00:00:00Z",
  "claimerTaxId": "12345678901",
  "keyType": "PHONE",
  "keyValue": "[phone]",
  "claimerBranch": "0001",
  "claimerTradeName": "Silva ME"
}
'

201

{
  "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

participantISPB · string · required

Claiming participant ISPB (8 numeric digits)

Body

application/json

PIX key ownership or portability claim to initiate (seven-day deadline; claimer and donor ISPB must differ)

claimType · enum<string> · required

Claim kind: OWNERSHIP (dispute the current owner) or PORTABILITY (move an existing key to this participant)

Available options: OWNERSHIP, PORTABILITY

Example:

"OWNERSHIP"

claimerAccountNumber · string · required

Claimer account number, 1 to 20 digits, the key would be bound to. BACEN admits letters here; this rail does not, and the door states the narrower rule it applies.

Pattern: ^[0-9]{1,20}$

Example:

"9988776"

claimerAccountType · enum<string> · required

Claimer account type: CACC, SVGS, TRAN, SLRY, or OTHR.

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

Example:

"CACC"

claimerName · string · required

Full legal name (CPF) or company name (CNPJ) of the claiming key owner, at most 150 characters (BACEN DICT 2.12.1 Person.Name).

Required string length: 1 - 150

Example:

"João Silva"

claimerOpeningDate · string<date-time> · required

Claimer account opening date, RFC 3339.

Example:

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

claimerTaxId · string · required

Claimer tax identifier: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (IN RFB 2.229/2024). Its length selects the BACEN person type, and the check digits are verified by the service.

Pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$

Example:

"12345678901"

keyType · enum<string> · required

PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP. Not every (claimType, keyType) pair is accepted: OWNERSHIP is claimable on PHONE only; PORTABILITY is claimable on CPF, CNPJ, PHONE, or EMAIL; EVP is claimable on neither.

Available options: CPF, CNPJ, EMAIL, PHONE, EVP

Example:

"PHONE"

keyValue · string · required

PIX key value being claimed (format depends on keyType: CPF, CNPJ, EMAIL, PHONE, or EVP). At most 77 characters, the ceiling BACEN publishes on a DICT key; the per-type shape is applied by the service, since one schema pattern cannot depend on keyType.

Required string length: 1 - 77

Example:

"[phone]"

claimerBranch · string

Claimer account branch (1..4 digits), optional.

Example:

"0001"

claimerTradeName · string

Claimer trade name (legal-entity claimers), optional.

Example:

"Silva ME"

Response

201

application/json

Created

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:

""