> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Get claim > Retrieves a single claim by its UUID. Local-first: a claim this participant lodged is answered from its own record; a DONOR-side claim another PSP opened against one of this participant's keys has no local record and is projected verbatim from BACEN's getClaim. Answers the whole claim entity, the claimer block included, the same shape every claim endpoint answers; a claim streaming fact carries the claim id, the claimed key and the two institutions, never the claimer. ## OpenAPI ````yaml /pt/openapi/v3-current/spi-dict.yaml get /api/v1/dict/claims/{claimID} openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: >- OpenAPI 3.1 surface for the DICT (Diretório de Identificadores de Contas Transacionais) capability of Lerian SPI, the direct integration between the institution and the Brazilian Instant Payment System (SPI/Pix). It covers the PIX key lifecycle, portability and ownership claims, the MED 2.0 dispute surface (infraction reports, refunds, fraud markers, and funds recoveries), antifraud statistics, synchronous DICT reports, and the internal operations that keep the key directory consistent. license: name: Lerian Studio General License title: Lerian SPI — DICT API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: [] tags: - description: 'PIX key lifecycle: register, list, search, lookup, delete, and statistics.' name: Keys - description: >- PIX key portability and ownership claims through their full lifecycle (initiate, confirm, reject, cancel, acknowledge, complete). name: Claims - description: 'DICT infraction reports: list and retrieve.' name: Infractions - description: 'DICT refund requests: create, list, and retrieve.' name: Refunds - description: 'PIX fraud markers: create, list, and statistics.' name: Fraud Markers - description: >- Durable MED operation-intent status: the operationId every create/lifecycle-transition backlog route returns or references on every outcome, queryable independently of the business resource. name: Operations - description: >- Synchronous reports over Lerian SPI's own DICT record: COUNT(*) summaries of keys (by type/status) and claims (by type/status + open-past-deadline). COUNT-only — DICT holds no money. name: Reports - description: 'Internal DICT operations: claim deadline processing.' name: Internal - description: >- DICT synchronism checks transported to BACEN for the participant named in X-ISPB: sync verification, CID resolution and CID set events, projected verbatim. name: VSync paths: /api/v1/dict/claims/{claimID}: get: tags: - Claims summary: Get claim description: >- Retrieves a single claim by its UUID. Local-first: a claim this participant lodged is answered from its own record; a DONOR-side claim another PSP opened against one of this participant's keys has no local record and is projected verbatim from BACEN's getClaim. Answers the whole claim entity, the claimer block included, the same shape every claim endpoint answers; a claim streaming fact carries the claim id, the claimed key and the two institutions, never the claimer. operationId: getClaim parameters: - description: Claim UUID in: path name: claimID required: true schema: description: Claim UUID format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ClaimResponse' description: Claim record with its current status and deadlines description: OK '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '429': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Too Many Requests '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: ClaimResponse: additionalProperties: false properties: bacen: $ref: '#/components/schemas/BACENEnvelopeResponse' description: >- BACEN's own operational envelope for its most recent interaction on this claim; omitted when no BACEN interaction has ever landed on it. bacenClaimId: description: >- 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. examples: - 550e8400-e29b-41d4-a716-446655440111 type: string cancelReason: description: >- 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 enum: - USER_REQUESTED - ACCOUNT_CLOSURE - FRAUD - DEFAULT_OPERATION - RECONCILIATION - RFB_VALIDATION - PARTICIPANT_EXCLUSION - COURT_ORDER type: string cancelledBy: description: >- 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 enum: - DONOR - CLAIMER type: string claimType: description: 'Claim kind: OWNERSHIP or PORTABILITY' examples: - OWNERSHIP type: string claimerAccountNumber: description: >- Number of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.AccountNumber). Answered on every claim projection, the list included examples: - '9988776' type: string claimerAccountType: description: >- Type of the account the claimed key would move to (ExtendedClaim.ClaimerAccount.AccountType). Answered on every claim projection, the list included enum: - CACC - SVGS - TRAN - SLRY - OTHR examples: - CACC type: string claimerBranch: description: >- 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 examples: - '0001' type: string claimerISPB: description: >- ISPB (8 digits or uppercase letters) of the participant initiating the claim examples: - '12345678' type: string claimerName: description: >- Name of the claiming key owner (ExtendedClaim.Claimer.Name). Answered on every claim projection, the list included; not carried on a claim streaming fact examples: - João Silva type: string claimerOpeningDate: description: >- 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 examples: - '2020-01-15T00:00:00Z' type: string claimerTaxId: description: >- 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 examples: - '11122233300' type: string claimerTradeName: description: >- 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 examples: - Silva ME type: string claimerType: description: >- 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 enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string completionPeriodEnd: description: >- 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. examples: - '2025-03-21T14:30:00Z' type: string confirmReason: description: >- 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 enum: - USER_REQUESTED - ACCOUNT_CLOSURE - FRAUD - DEFAULT_OPERATION - RECONCILIATION - RFB_VALIDATION - PARTICIPANT_EXCLUSION type: string deadline: description: >- 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. examples: - '2025-03-14T14:30:00Z' type: string donorISPB: description: >- ISPB (8 digits or uppercase letters) 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. examples: - '87654321' type: string id: description: Server-assigned claim UUID examples: - 550e8400-e29b-41d4-a716-446655440000 type: string keyType: description: 'PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP' examples: - PHONE type: string keyValue: description: PIX key value under claim examples: - '+5511999999999' type: string lastModified: description: >- 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. examples: - '2025-03-07T14:30:00Z' type: string requestedAt: description: >- Claim initiation timestamp (RFC 3339, UTC); omitted for a donor-side claim projected from BACEN, whose ExtendedClaim carries no creation time examples: - '2025-03-07T14:30:00Z' type: string resolution: description: >- 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, NOT_REGISTERED_AT_BACEN); empty until the claim resolves — CONFIRMED is not terminal and never sets this field examples: - '' type: string resolutionPeriodEnd: description: >- 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 examples: - '2025-03-14T14:30:00Z' type: string resolvedAt: description: >- Resolution timestamp (RFC 3339, UTC); omitted while the claim is unresolved examples: - '' type: string status: description: >- Claim lifecycle state: OPEN, WAITING_RESOLUTION, CONFIRMED, CANCELLED, or COMPLETED examples: - OPEN type: string required: - id - claimType - keyValue - keyType - claimerISPB - status - deadline type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string correlationId: description: Request-scoped correlation identifier echoing X-Request-ID. examples: - req-7a3f9c2e type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. required: - correlationId type: object BACENEnvelopeResponse: additionalProperties: false properties: correlationId: description: >- BACEN's own correlation identifier for its most recent interaction on this record — the wire value, distinct from any request-scoped echo. examples: - a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 type: string lastModified: description: >- BACEN's own LastModified for this resource (RFC 3339, UTC) — the version this response reflects; present only on the MED resources (infraction, refund, fraud marker, funds recovery). examples: - '2026-06-14T12:00:00Z' type: string responseTime: description: >- Instant BACEN answered its most recent interaction on this record, RFC 3339 (UTC); omitted when BACEN's response carried no parseable instant. examples: - '2026-06-14T12:00:00Z' type: string required: - correlationId type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.