Ledga
POST /transactions/search

Search the ledger's transactions by their attributes

Return the API key's ledger's transactions whose attributes match every predicate, within a transaction_created_at window of at most 12 months, newest first. Operators: eq, in (1-50 values), prefix (at least 2 characters, matched literally), and gt/gte/lt/lte on keys declared integer, decimal or date (a range on any other key is a 422). A typed key's values are compared in their canonical form. Every limit is enforced as a 422 before any query runs.

Request bodyrequired

FieldTypeDescription

Responses

200The matching transactions (empty data when none match)
{
  "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 ledger context)
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
422A filter outside the limits: no or too long a window, no or too many predicates or groups, too many in values, a short prefix or text, a range on an untyped key, a value not of its key's type, a bad cursor or limit, a cursor of another sort; or code SEARCH_TOO_BROAD when the search ran past its 5 s statement timeout (narrow its window or lead with an eq predicate), INVALID_REFERENCE for an id that is not the ledger's, AMOUNT_NOT_READY before the ledger's stored totals are verified, SEARCH_NOT_READY before text search's or the effective-date sort's index is built
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
429Search rate limit exceeded (60 a minute per API key, 120 per ledger)
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}

Examples

curl -X POST https://ledga.io/api/v1/transactions/search \
  -H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -d '{
  "transaction_created_at": {
    "from": "2026-01-01T00:00:00Z",
    "to": "2026-06-30T23:59:59Z"
  },
  "attributes": [
    {
      "key": "customer_id",
      "op": "eq",
      "value": "C-123",
      "values": [
        "string"
      ]
    }
  ],
  "account_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
  "status": "posted",
  "layer": "settled",
  "effective_date": {
    "from": "2026-01-15",
    "to": "2026-01-15"
  },
  "limit": 25,
  "cursor": "string"
}'

← All endpoints