GET
/transactions/by-attribute Search transactions by a searchable business dimension (tenant-scoped, cross-ledger)
Return the transactions carrying a given key=value dimension (e.g. customer_id=C-123), newest first. Tenant-scoped and cross-ledger by default; the tenant is derived server-side from the API key and is never taken from the query string. A value that exists only in another tenant returns an empty paginator (never a 404). Optional ledger_id narrows to one ledger; optional from/to bound the transaction_created_at window.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
keyrequired | query | string max length: 64 | Attribute key (dimension) to search on, e.g. customer_id |
valuerequired | query | string max length: 128 | Exact attribute value to match, e.g. C-123 |
ledger_id | query | string uuid | Optional — narrow the search to a single ledger within the tenant |
from | query | string | Optional inclusive lower bound on the transaction's creation time, in UTC. Format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS, with no offset. A window narrows the search. |
to | query | string | Optional inclusive upper bound on the transaction's creation time, in UTC. Format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS, with no offset. |
limit | query | integer default: 25 · min: 1 · max: 100 | Items per page, 1 to 100. |
cursor | query | string | The previous page's meta.pagination.next_cursor; omit it for the first page. A cursor not shaped like this list's is a 422. |
Responses
200Successful operation (empty data when no transaction in this tenant carries the dimension)
{
"success": true,
"meta": {
"pagination": {
"limit": 25,
"has_more": true,
"next_cursor": "eyJpZCI6IjAxOTk3YzFlLTRkMmEtN2MzZS05YTFiLTJmMGU4YzZkNGI1YSJ9",
"previous_cursor": null
}
},
"data": [
{
"id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"ledger_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"journal_id": null,
"reference": "INV-001",
"description": "Payment received",
"effective_date": "2026-01-15T10:30:00Z",
"date": "2026-01-15T10:30:00Z",
"layer": "settled",
"status": "posted",
"total_amount": "100.00",
"entry_count": 2,
"hash": null,
"previous_hash": null,
"correlation_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"correlation_source_id": null,
"correlation_type": null,
"metadata": null,
"attributes": {
"customer_id": "C-123",
"loan_id": "L-42"
},
"original_transaction_id": null,
"reversal_reason": null,
"voided_by": null,
"voided_at": null,
"void_reason": null,
"entries": [
{
"id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"account_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"account_code": "1000",
"account_name": "Cash",
"amount": "100.00",
"type": "debit",
"description": null,
"layer": "settled",
"metadata": null
}
],
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
]
} 401Unauthenticated
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 403Forbidden (no tenant context)
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 422Validation error (key or value missing, too long or not UTF-8 text, bad ledger_id/date); or a cursor not shaped like this list's
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} Examples
curl https://ledga.io/api/v1/transactions/by-attribute?key=string&value=string \
-H "Authorization: Bearer sk_xxxxxxxx_your_secret"