List PIX Key Claims

GET https://api.somossimpay.com.br/v3/dict/claim

Retrieve a list of all PIX key claims associated with a specific account. This endpoint allows you to monitor the status of ongoing claims, view completed claims, and track claim history.

Endpoint

GET /v3/dict/claim

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo

Query Parameters

Parameter	Type	Description	Required or Optional	Example
source_account_branch_identifier	String	Branch identifier of the account	required	0001
source_account_number	String	Account number to list claims for	required	12345678
status	String	Filter by claim status. Valid values: OPEN, WAITING_RESOLUTION, CONFIRMED, COMPLETED, CANCELLED	optional	OPEN

Request Examples

List all claims for an account:

HTTP

GET /v3/dict/claim?source_account_branch_identifier=0001&source_account_number=12345678
Authorization: Bearer access_token_here

List only open claims:

HTTP

GET /v3/dict/claim?source_account_branch_identifier=0001&source_account_number=12345678&status=OPEN
Authorization: Bearer access_token_here

List confirmed claims:

HTTP

GET /v3/dict/claim?source_account_branch_identifier=0001&source_account_number=12345678&status=CONFIRMED
Authorization: Bearer access_token_here

Response Details

Response

{
  "worked": true,
  "claims": [
    {
      "pix_key_claim_id": "abc123def456ghi789",
      "claim_id": "123e4567-e89b-12d3-a456-426655440000",
      "type": "CELL_PHONE",
      "key": "[phone]",
      "role": "CLAIMER",
      "claim_type": "PORTABILITY",
      "status": "OPEN",
      "source_account_branch_identifier": "0001",
      "source_account_number": "12345678",
      "resolution_deadline": "2024-12-31T23:59:59.999Z",
      "conclusion_deadline": null,
      "last_modification_datetime": "2024-12-24T10:30:00.000Z",
      "counterpart_ispb": "12345678",
      "confirmation_reason": null,
      "cancellation_reason": null,
      "cancelled_by_role": null,
      "cancelled_by_name": null,
      "confirmed_by_name": null,
      "completed_by_name": null,
      "created_by_name": "John Doe",
      "created_at": "2024-12-24T10:30:00.000Z"
    },
    {
      "pix_key_claim_id": "xyz789abc012def345",
      "claim_id": "987f6543-c21b-34d5-e678-890123456789",
      "type": "CPF",
      "key": "12345678901",
      "role": "DONOR",
      "claim_type": "OWNERSHIP",
      "status": "WAITING_RESOLUTION",
      "source_account_branch_identifier": "0001",
      "source_account_number": "12345678",
      "resolution_deadline": "2024-12-31T23:59:59.999Z",
      "conclusion_deadline": "2025-01-02T23:59:59.999Z",
      "last_modification_datetime": "2024-12-25T14:20:00.000Z",
      "counterpart_ispb": "87654321",
      "confirmation_reason": null,
      "cancellation_reason": null,
      "cancelled_by_role": null,
      "cancelled_by_name": null,
      "confirmed_by_name": null,
      "completed_by_name": null,
      "created_by_name": "Jane Smith",
      "created_at": "2024-12-25T14:20:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
worked	Boolean	Always true for successful requests.
claims	Array	Array of claim objects matching the query criteria

Claim Object Fields

Field	Type	Description
pix_key_claim_id	String	Internal database ID for this claim record
claim_id	String	DICT claim identifier (UUID format). May be null if not yet synced with DICT
type	String	PIX key type being claimed (CPF, CNPJ, CELL_PHONE, EMAIL)
key	String	The PIX key value being claimed
role	String	Role in this claim: CLAIMER (requesting) or DONOR (current holder)
claim_type	String	Type of claim: PORTABILITY or OWNERSHIP
status	String	Current claim status: OPEN, WAITING_RESOLUTION, CONFIRMED, COMPLETED, CANCELLED
source_account_branch_identifier	String	Branch identifier of the account
source_account_number	String	Account number
resolution_deadline	String	Deadline for donor to respond (ISO 8601 format). May be null
conclusion_deadline	String	Deadline for claimer to conclude (ownership claims only - ISO 8601 format). May be null
last_modification_datetime	String	Last modification timestamp from DICT (ISO 8601 format). May be null
counterpart_ispb	String	ISPB of the counterpart institution. May be null
confirmation_reason	String	Reason for confirmation if claim was confirmed. May be null
cancellation_reason	String	Reason for cancellation if claim was cancelled. May be null
cancelled_by_role	String	Role of who cancelled (CLAIMER or DONOR). May be null
cancelled_by_name	String	Name of the user who cancelled. May be null
confirmed_by_name	String	Name of the user who confirmed. May be null
completed_by_name	String	Name of the user who completed. May be null
created_by_name	String	Name of the user who created the claim. May be null
created_at	String	Timestamp when the claim was created locally (ISO 8601 format)

Error Responses

HTTP Code	Error Message	Description
400	Company not found	The company associated with the authenticated user was not found
400	Account not found	The source account was not found or is not active
400	AccountBank is closed	The account is closed and cannot be accessed
401	Unauthorized	Invalid or missing authentication token
422	Validation error	Request validation failed. Check that all required query parameters are present and in the correct format.

Business Rules

Authorization:

• You must have access to the specified account
• Only claims associated with accounts you can access are returned

Filtering:

• Required filters: source_account_branch_identifier and source_account_number are mandatory
• Optional filter: status can be provided to filter by a specific claim status
• If no status is provided, all claims for the account are returned

Claim Roles:
You will see two types of claims in the results:

• CLAIMER: Claims where your account is requesting to receive the key
• DONOR: Claims where your account currently holds the key and someone is claiming it

Status Values:

• OPEN: Claim initiated, waiting for donor to read
• WAITING_RESOLUTION: Donor has read the claim, waiting for action
• CONFIRMED: Donor confirmed the claim
• COMPLETED: Claim successfully completed
• CANCELLED: Claim was cancelled

Sorting:

• Claims are returned with most recent first (by creation date)
• You can use the created_at field to determine claim age

Important Notes:

• The response includes historical claims (completed and cancelled)
• Claims with null claim_id are still pending synchronization with DICT
• Deadlines shown are in ISO 8601 format with timezone information
• The counterpart_ispb identifies the other institution involved in the claim
• User names (created_by, confirmed_by, etc.) are included for audit purposes

Use Cases:

1. Monitor pending claims: Filter by status=OPEN or status=WAITING_RESOLUTION to see claims needing action
2. Check claim history: Retrieve all claims without status filter to see complete history
3. Donor notifications: Filter by role=DONOR to see claims where you need to confirm/cancel
4. Claimer tracking: Filter by role=CLAIMER to monitor your outgoing claim requests
5. Audit trail: Use the various _by_name fields to track who performed each action

Performance Considerations:

• This endpoint is optimized for single-account queries
• For bulk operations across multiple accounts, make separate requests
• Results are not paginated - all matching claims are returned
• Typical response times are under 500ms for accounts with moderate claim history