Create a portability or ownership claim

​

Creates a new claim to transfer a Pix key from a donor institution to a claimer institution. Supports both PORTABILITY (same owner, different institution) and OWNERSHIP (different owner) claim types.

Headers
  • Idempotency-Key
    Type: string
    required

    Unique idempotency key for the request (UUID format)

Body·
required
application/json

Request to create a portability claim

  • claimer
    Type: object ·
    required

    Claimant (new key holder) identification information

  • claimerAccount
    Type: object ·
    required

    Claimant institution account information

  • key
    Type: string
    min length:  
    1
    required

    Pix key value being claimed

  • keyType
    Type: string enum
    required

    Type of the Pix key being claimed

    values
    • EVP
    • CPF
    • CNPJ
    • PHONE
    • EMAIL
  • type
    Type: string enum
    required

    Claim type: PORTABILITY (same owner, different institution) or OWNERSHIP (different owner)

    values
    • PORTABILITY
    • OWNERSHIP
Responses
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/claims
curl http://localhost:8080/api/v1/claims \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "type": "PORTABILITY",
  "keyType": "EVP",
  "key": "",
  "claimer": {
    "personType": "NATURAL_PERSON",
    "taxId": "",
    "name": "",
    "tradeName": ""
  },
  "claimerAccount": {
    "participant": "",
    "branch": "",
    "accountNumber": "",
    "accountType": "CACC",
    "openingDate": ""
  }
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "dictClaimId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "PORTABILITY",
  "key": "string",
  "keyType": "EVP",
  "status": "OPEN",
  "claimerParticipant": "string",
  "donorParticipant": "string",
  "claimer": {
    "personType": "string",
    "taxId": "string",
    "name": "string",
    "tradeName": "string"
  },
  "claimerAccount": {
    "participant": "string",
    "branch": "string",
    "accountNumber": "string",
    "accountType": "string",
    "openingDate": "string"
  },
  "resolutionPeriodEnd": "2026-07-29T19:28:46.731Z",
  "completionPeriodEnd": "2026-07-29T19:28:46.731Z",
  "closingPeriodEnd": "2026-07-29T19:28:46.731Z",
  "expiresAt": "2026-07-29T19:28:46.731Z",
  "isDonor": true,
  "isClaimer": true,
  "cancelReason": "USER_REQUESTED",
  "cancelledBy": "DONOR",
  "confirmedBy": "DONOR",
  "completedBy": "CLAIMER",
  "lastModified": "2026-07-29T19:28:46.731Z",
  "requestedAt": "2026-07-29T19:28:46.731Z",
  "acknowledgedAt": "2026-07-29T19:28:46.731Z",
  "confirmedAt": "2026-07-29T19:28:46.731Z",
  "cancelledAt": "2026-07-29T19:28:46.731Z",
  "completedAt": "2026-07-29T19:28:46.731Z"
}

Claim created successfully.