DICT API Reference

The DICT API endpoints are served by the Settlement Service gateway on port 4003, which proxies requests to the DICT Service on port 4001. All endpoints require JWT authentication.

Base URL: http://localhost:4003/api/v1

Key Management

Create Key

Register a new PIX key for an account.

POST /keys

Request Body:

{
  "key_type": "cpf",
  "key_value": "12345678901",
  "account": {
    "participant_ispb": "12345678",
    "branch": "0001",
    "account_number": "123456",
    "account_type": "CACC"
  },
  "owner": {
    "type": "NATURAL_PERSON",
    "tax_id": "12345678901",
    "name": "Maria Silva"
  }
}

Key Type Values:

Type	Format	Example
cpf	11 digits	12345678901
cnpj	14 digits	11222333000181
phone	E.164	+5511999887766
email	Email address	user@example.com
evp	(auto-generated)	Leave key_value empty

Response: 201 Created

{
  "key_type": "cpf",
  "key_value": "12345678901",
  "account": {
    "participant_ispb": "12345678",
    "branch": "0001",
    "account_number": "123456",
    "account_type": "CACC"
  },
  "owner": {
    "type": "NATURAL_PERSON",
    "tax_id": "12345678901",
    "name": "Maria Silva"
  },
  "cid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Responses:

Status	Code	Description
400	INVALID_KEY_FORMAT	Key value doesn't match the expected format
400	KEY_LIMIT_EXCEEDED	Owner has reached the maximum number of keys
409	KEY_ALREADY_EXISTS	Key is already registered by another participant
409	KEY_OWNED_BY_ANOTHER	Key belongs to a different owner (use claim)
422	INVALID_ACCOUNT	Account information is invalid

---

Lookup Key

Retrieve account information associated with a PIX key.

POST /keys/lookup

Request Body:

{
  "key": "+5511999887766"
}

Response: 200 OK

{
  "key_type": "phone",
  "key_value": "+5511999887766",
  "account": {
    "participant_ispb": "87654321",
    "branch": "0002",
    "account_number": "654321",
    "account_type": "CACC"
  },
  "owner": {
    "type": "NATURAL_PERSON",
    "tax_id": "***456***01",
    "name": "Jo** Si***"
  },
  "cid": "f1e2d3c4-b5a6-7890-dcba-fe0987654321",
  "status": "active",
  "created_at": "2024-01-10T08:00:00Z"
}

INFO

Owner information is partially masked in lookup responses as required by BACEN privacy regulations. Full details are only available for keys owned by your institution.

---

List Keys

List PIX keys registered by your institution.

GET /keys

Query Parameters:

Parameter	Type	Description
key_type	string	Filter by key type
status	string	Filter by status (active, pending, removed)
owner_tax_id	string	Filter by owner CPF/CNPJ
account_number	string	Filter by account number
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)
sort	string	Sort field (default: created_at)
order	string	Sort direction: asc or desc

Response: 200 OK

{
  "data": [
    {
      "key_type": "cpf",
      "key_value": "12345678901",
      "status": "active",
      "owner": { "name": "Maria Silva" },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1542,
    "total_pages": 78
  }
}

---

Get Key Details

Retrieve full details for a specific key.

GET /keys/:key_value

Response: 200 OK

Returns the same structure as the Create Key response.

---

Delete Key

Remove a registered PIX key.

DELETE /keys/:key_value

Response: 204 No Content

Error Responses:

Status	Code	Description
404	KEY_NOT_FOUND	Key does not exist or is not owned by your institution
409	KEY_HAS_ACTIVE_CLAIM	Key has a pending claim and cannot be removed
423	KEY_LOCKED	Key is temporarily locked (retry later)

---

Claims

Create Claim

Initiate a portability or ownership claim for a PIX key.

POST /claims

Request Body:

{
  "claim_type": "PORTABILITY",
  "key_type": "phone",
  "key_value": "+5511999887766",
  "claimer_account": {
    "participant_ispb": "12345678",
    "branch": "0001",
    "account_number": "123456",
    "account_type": "CACC"
  }
}

Claim Types:

Type	Description	Resolution Period
PORTABILITY	Transfer key to your institution	7 calendar days
OWNERSHIP	Transfer key to different owner	14 calendar days

Response: 201 Created

{
  "claim_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
  "claim_type": "PORTABILITY",
  "key_value": "+5511999887766",
  "status": "OPEN",
  "donor_ispb": "87654321",
  "claimer_ispb": "12345678",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-22T10:30:00Z"
}

---

Update Claim

Confirm, deny, or cancel a claim. Used by the donor institution to respond.

PUT /claims/:claim_id

Request Body:

{
  "action": "CONFIRM"
}

Actions:

Action	Actor	Description
CONFIRM	Donor	Accept the claim, transfer the key
DENY	Donor	Reject the claim (must provide reason)
CANCEL	Claimer	Withdraw the claim

Response: 200 OK

{
  "claim_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
  "status": "CONFIRMED",
  "resolved_at": "2024-01-16T14:00:00Z"
}

---

List Claims

GET /claims

Query Parameters:

Parameter	Type	Description
status	string	OPEN, CONFIRMED, DENIED, CANCELLED
claim_type	string	PORTABILITY or OWNERSHIP
role	string	donor or claimer
page	integer	Page number
per_page	integer	Items per page

---

Infractions

Create Infraction Report

POST /infractions

Request Body:

{
  "end_to_end_id": "E1234567820240115120012345678901",
  "infraction_type": "FRAUD",
  "report_details": "Unauthorized transaction reported by account holder"
}

Infraction Types:

Type	Description
FRAUD	Confirmed or suspected fraud
REQUEST_REFUND	Account holder requests refund
ACCOUNT_CLOSURE	Account closed, funds need return

Response: 201 Created

{
  "infraction_id": "inf-123456",
  "end_to_end_id": "E1234567820240115120012345678901",
  "infraction_type": "FRAUD",
  "status": "OPEN",
  "created_at": "2024-01-15T10:30:00Z"
}

---

Common Response Codes

Status	Description
200	Success
201	Resource created
204	Deleted successfully (no body)
400	Validation error
401	Invalid or missing authentication
403	Insufficient permissions
404	Resource not found
409	Conflict (duplicate, active claim, etc.)
422	Unprocessable entity
423	Resource locked
429	Rate limited
500	Internal server error
503	Service unavailable (BACEN connectivity)

Pagination

All list endpoints support pagination:

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1542,
    "total_pages": 78
  }
}

Use page and per_page query parameters. Maximum per_page is 100.