Querying Customer Records
List customer records, fetch summary metrics, and inspect customer-level activity.
Use these API-key-authenticated endpoints to work with customer records.
Base URL: https://balance-api.pacspace.io/api/v1/balance
Required header:
bash
-H "X-Api-Key: YOUR_API_KEY"
List Customer Records
http
GET /customers
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page index (1-based) |
limit | number | 25 | Page size |
search | string | — | Filter by customer ID |
Example:
bash
curl "https://balance-api.pacspace.io/api/v1/balance/customers?page=1&limit=25" \
-H "X-Api-Key: YOUR_API_KEY"
Get Customer Summary
http
GET /customers/summary
Returns aggregate metrics across your customer records (counts, totals, and verification health).
Example:
bash
curl https://balance-api.pacspace.io/api/v1/balance/customers/summary \
-H "X-Api-Key: YOUR_API_KEY"
Get Customer Record Detail
http
GET /customers/:customerId
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
deltaPage | number | 1 | Activity page |
deltaLimit | number | 20 | Activity size |
Example:
bash
curl "https://balance-api.pacspace.io/api/v1/balance/customers/cust_001?deltaPage=1&deltaLimit=20" \
-H "X-Api-Key: YOUR_API_KEY"
Sample response shape:
json
{
"success": true,
"data": {
"customerId": "cust_001",
"customerReference": "0xA1b2C3d4E5f6789012345678901234567890Ef34",
"customerPartition": "1234567890",
"totalDeltas": 42,
"computedBalance": 4500,
"latestCheckpoint": "chk_abc123",
"recentActivity": {
"items": [
{
"delta": 100,
"reason": "deposit",
"referenceId": "txn_01",
"status": "verified",
"time": "2026-02-14T14:22:00.000Z",
"recordId": "rec_123",
"verificationReference": "0xabc..."
}
]
}
}
}
SDK Example
typescript
const { customers } = await pac.balance.customers({ limit: 10 });
const customer = await pac.balance.customer('cust_001');
Errors
| Status | Code | Description |
|---|---|---|
404 | CUSTOMER_NOT_FOUND | No customer record exists for this ID |
429 | RATE_LIMIT_EXCEEDED | Rate limit exceeded |
500 | LIST_CUSTOMERS_FAILED | Listing failed |
500 | GET_CUSTOMER_FAILED | Detail retrieval failed |
Isolation
Customer records are tenant-scoped. You can access only records associated with your API key.