Skip to main content
POST
/
search
/
{collection}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "status:=APPLIED && currency:=USD",
    "sort_by": "created_at:desc",
    "page": 1,
    "per_page": 10
  }'

{
  "facet_counts": [],
  "found": 2,
  "hits": [
    {
      "document": {
        "amount": 532,
        "created_at": 1758116489,
        "currency": "USD",
        "description": "Test transaction",
        "destination": "bln_20666087-1355-4736-ba04-3ba92a7542b9",
        "id": "txn_cd728825-a6e1-4fae-9277-c3235a045ea5",
        "precise_amount": 53200,
        "precision": 100,
        "reference": "ref-001",
        "source": "bln_93fb50c2-969e-49c2-bb61-ef5ed245516e",
        "status": "APPLIED",
        "transaction_id": "txn_cd728825-a6e1-4fae-9277-c3235a045ea5"
      },
      "highlights": [],
      "text_match": 578730123365711993
    }
  ],
  "out_of": 232,
  "page": 1,
  "per_page": 10,
  "request_params": {
    "collection_name": "transactions",
    "per_page": 10,
    "q": "*"
  },
  "search_cutoff": false,
  "search_time_ms": 2
}

​
Authorization

If set, the API uses an API key for authentication. Include the following header in your requests: X-blnk-key: <api-key>. Replace <api-key> with your secret API key. Ensure the key is kept secure and not exposed in public repositories or client-side code. See also: Secure your Blnk server
Available in version 0.6.1 and later.
The Search API enables you to retrieve one or more records from your ledger with advanced filtering, sorting, and full-text search capabilities. Unlike standard GET endpoints, the Search API gives you more control over your results.

​
Path Parameters

​
collection
string
required
The collection to search. Supported values:
  • transactions - Search through all transaction records
  • balances - Find balance records across all ledgers
  • ledgers - Locate specific ledgers by name or metadata
  • identities - Search customer identity records

​
Body

​
q
string
required
The search query text. Use * to return all records. Supports full-text search when combined with query_by. Learn more: Querying
​
query_by
string
Comma-separated list of fields to search in. When provided, performs field-specific searches. Learn more: QueryingExamples:
  • "source,destination" - Search in source and destination fields
  • "first_name,last_name,email" - Search in identity name and email fields
​
filter_by
string
Filter conditions to refine results. Supports operators like :=, :>, :<, :>=, :<=, :!=, and ranges. Learn more: FilteringExamples:
  • "status:=APPLIED" - Filter by exact status
  • "amount:>1000" - Filter by amount greater than 1000
  • "status:=APPLIED && currency:=USD" - Multiple conditions
  • "created_at:[1704067200..1706745599]" - Date range filter
​
sort_by
string
Sorting conditions for ordering results. Format: field:direction where direction is asc or desc. Multiple fields: field1:desc,field2:asc. Learn more: SortingExamples:
  • "created_at:desc" - Sort by creation date descending
  • "amount:desc,created_at:asc" - Sort by amount then date
​
page
integer
Page number for pagination. Starts at 1. Default: 1. Learn more: Pagination
​
per_page
integer
Number of results per page. Maximum 250, default 10. Learn more: Pagination

​
Response

​
found
integer
Total number of matching records.
​
hits
array
Array of search results. Each hit contains a document object with the record data and optional highlights for matched terms.
​
out_of
integer
Total number of records in the collection (regardless of filters).
​
page
integer
Current page number.
​
per_page
integer
Number of results per page.
​
search_time_ms
integer
Time taken to execute the search in milliseconds.
​
highlights
array
Search term highlighting information for matched fields. Only present when full-text search matches are found.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "status:=APPLIED && currency:=USD",
    "sort_by": "created_at:desc",
    "page": 1,
    "per_page": 10
  }'

{
  "facet_counts": [],
  "found": 2,
  "hits": [
    {
      "document": {
        "amount": 532,
        "created_at": 1758116489,
        "currency": "USD",
        "description": "Test transaction",
        "destination": "bln_20666087-1355-4736-ba04-3ba92a7542b9",
        "id": "txn_cd728825-a6e1-4fae-9277-c3235a045ea5",
        "precise_amount": 53200,
        "precision": 100,
        "reference": "ref-001",
        "source": "bln_93fb50c2-969e-49c2-bb61-ef5ed245516e",
        "status": "APPLIED",
        "transaction_id": "txn_cd728825-a6e1-4fae-9277-c3235a045ea5"
      },
      "highlights": [],
      "text_match": 578730123365711993
    }
  ],
  "out_of": 232,
  "page": 1,
  "per_page": 10,
  "request_params": {
    "collection_name": "transactions",
    "per_page": 10,
    "q": "*"
  },
  "search_cutoff": false,
  "search_time_ms": 2
}
For simple operations like retrieving a single record by ID or listing all records, use the standard GET endpoints. Use the Search API when you need filtering, sorting, or complex queries.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.
Tip: Connect to Blnk Cloud to see your Core data.You can view your transactions, manage identities, create custom reports, invite other team members to collaborate, and perform operations on your Core — all in one dashboard.Check out Blnk Cloud →