--- updatedAt: 2026-06-11T17:29:53.000Z --- Fetch the complete documentation index at: https://simpay-prod.readme.io/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # List PIX Key Claims 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 ```json Response { "worked": true, "claims": [ { "pix_key_claim_id": "abc123def456ghi789", "claim_id": "123e4567-e89b-12d3-a456-426655440000", "type": "CELL_PHONE", "key": "+5511999999999", "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 # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "Banking & PIX API", "description": "Complete API documentation for the banking and PIX payment platform." }, "servers": [ { "url": "https://api.somossimpay.com.br/" } ], "security": [], "tags": [ { "name": "DICT-API", "description": "DICT-API endpoints" } ], "paths": { "/v3/dict/claim": { "get": { "operationId": "get_dict_claim", "summary": "List PIX Key Claims", "description": "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.", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": true, "samples-languages": [ "curl", "python", "javascript", "java", "go" ] } } ```