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
`key`required	query	string max length: 64	Attribute key (dimension) to search on, e.g. customer_id
`value`required	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 transaction_created_at (enables partition pruning). Format `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` — NO timezone (the column is timestamp without time zone).
`to`	query	string	Optional inclusive upper bound on transaction_created_at (enables partition pruning). Format `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` — NO timezone (the column is timestamp without time zone).
`limit`	query	integer default: 25 · min: 1 · max: 100	Number of items per page (1-100)
`cursor`	query	string	Opaque keyset cursor returned by this endpoint. A malformed or foreign cursor is rejected as 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": "eyJpZCI6IjAxOWRjZjg3LTUwN2ItNzE5OS05ZTE1LWZhY2YxNjVlNzRjMSJ9"
    }
  },
  "data": [
    {
      "id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
      "ledger_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
      "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,
      "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",
          "layer": "settled"
        }
      ],
      "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 (missing/too-long key or value, bad ledger_id/date)

{
  "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"

← All endpoints