Search via Typesense

Available in version 0.6.1 and later.

The Blnk Search API enables you to retrieve one or more records from your ledger. You can search across ledgers, balances, transactions, and identities using its filtering, sorting, faceting, and full-text search capabilities. Unlike the standard GET endpoints that return either all records or a single specific record, the Search API gives you more control over your results. Use it when you need to:

Filter large datasets efficiently
Perform full-text searches across your data
Aggregate and count values with faceting
Sort and paginate results for better performance
Combine multiple search conditions in a single request

Searchable collections

The Search API works with four main collections in your Blnk ledger:

Collection	Endpoint	Description
Transactions	`/search/transactions`	Search through all transaction records
Balances	`/search/balances`	Find balance records across all ledgers
Ledgers	`/search/ledgers`	Locate specific ledgers by name or metadata
Identities	`/search/identities`	Search customer identity records

Quick start

To get started with the Search API, use the endpoint: /search/{collection} where collection can be ledgers, balances, identities, or transactions. Here’s how a full search request looks:

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "bulk_baaea495-148a-4b16-b171-68c92fb911a6",
    "query_by": "parent_transaction",
    "filter_by": "status:=APPLIED && currency:=USD",
    "sort_by": "created_at:desc",
    "page": 1,
    "per_page": 10
  }'

const response = await blnk.Search.search(
  {
    q: 'bulk_baaea495-148a-4b16-b171-68c92fb911a6',
    query_by: 'parent_transaction',
    filter_by: 'status:=APPLIED && currency:=USD',
    sort_by: 'created_at:desc',
    page: 1,
    per_page: 10,
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "bulk_baaea495-148a-4b16-b171-68c92fb911a6",
        QueryBy: "parent_transaction",
        FilterBy: "status:=APPLIED && currency:=USD",
        SortBy: "created_at:desc",
        Page: 1,
        PerPage: 10,
    },
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "bulk_baaea495-148a-4b16-b171-68c92fb911a6",
    "query_by": "parent_transaction",
    "filter_by": "status:=APPLIED && currency:=USD",
    "sort_by": "created_at:desc",
    "page": 1,
    "per_page": 10,
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("bulk_baaea495-148a-4b16-b171-68c92fb911a6")
        .queryBy("parent_transaction")
        .filterBy("status:=APPLIED && currency:=USD")
        .sortBy("created_at:desc")
        .page(1)
        .perPage(10),
    "transactions"
);

Response

{
  "facet_counts": [],
  "found": 2,
  "hits": [
    {
      "document": {
        "amount": 532,
        "amount_string": "532",
        "atomic": false,
        "created_at": 1758116489,
        "currency": "USD",
        "description": "Test bulk",
        "destination": "bln_20666087-1355-4736-ba04-3ba92a7542b9",
        "effective_date": 1758116489,
        "id": "txn_cd728825-a6e1-4fae-9277-c3235a045ea5",
        "parent_transaction": "bulk_baaea495-148a-4b16-b171-68c92fb911a6",
        "precise_amount": 53200,
        "precision": 100,
        "reference": "bulk-search-1d2",
        "source": "bln_93fb50c2-969e-49c2-bb61-ef5ed245516e",
        "status": "APPLIED",
        "transaction_id": "txn_cd728825-a6e1-4fae-9277-c3235a045ea5"
      },
      "highlights": [
        {
          "field": "parent_transaction",
          "matched_tokens": ["bulk_baaea495-148a-4b16-b171-68c92fb911a6"],
          "snippet": "<mark>bulk_baaea495-148a-4b16-b171-68c92fb911a6</mark>"
        }
      ],
      "text_match": 578730123365711993
    },
    {
      "document": {
        "amount": 100,
        "amount_string": "100",
        "atomic": false,
        "created_at": 1758116489,
        "currency": "USD",
        "description": "Test bulk",
        "destination": "bln_d298f2b8-fdd6-4d0e-ade7-3cddcea90a8d",
        "effective_date": 1758116489,
        "id": "txn_0ae624a5-7fbc-4c67-831d-f888e928d4bc",
        "parent_transaction": "bulk_baaea495-148a-4b16-b171-68c92fb911a6",
        "precise_amount": 10000,
        "precision": 100,
        "reference": "bulk-search-2d3",
        "source": "bln_6592f225-f8fe-48cd-8974-51974dc83a3a",
        "status": "APPLIED",
        "transaction_id": "txn_0ae624a5-7fbc-4c67-831d-f888e928d4bc"
      },
      "highlights": [
        {
          "field": "parent_transaction",
          "matched_tokens": ["bulk_baaea495-148a-4b16-b171-68c92fb911a6"],
          "snippet": "<mark>bulk_baaea495-148a-4b16-b171-68c92fb911a6</mark>"
        }
      ],
      "text_match": 578730123365711993
    }
  ],
  "out_of": 232,
  "page": 1,
  "request_params": {
    "collection_name": "transactions",
    "per_page": 10,
    "q": "bulk_baaea495-148a-4b16-b171-68c92fb911a6"
  },
  "search_cutoff": false,
  "search_time_ms": 2
}

Request parameters

Parameter	Description	Required	Type
`q`	The search query text. Use `*` to return all records. Learn more	Yes	`string`
`query_by`	Comma-separated list of fields to search in. Learn more	No	`string`
`filter_by`	Filter conditions to refine results. Learn more	No	`string`
`facet_by`	Comma-separated list of fields to aggregate and count. Learn more	No	`string`
`sort_by`	Sorting conditions for ordering results. Learn more	No	`string`
`page`	Page number for pagination. Starts at 1. Learn more	No	`integer`
`per_page`	Number of results per page. Maximum 250, default 10. Learn more	No	`integer`

Response structure

Field	Description	Type
`found`	Total number of matching records.	`integer`
`hits`	Array of search results, each containing a `document` with the record data.	`array`
`out_of`	Total number of records in the collection.	`integer`
`page`	Current page number.	`integer`
`search_time_ms`	Time taken to execute the search in milliseconds.	`integer`
`facet_counts`	Aggregated counts for faceted fields. Only present when using `facet_by`. Learn more	`array`
`highlights`	Search term highlighting information for matched fields.	`array`

Common use cases

1. Transaction analysis

Find all transactions for a specific account

Get a complete transaction history by searching for all transactions where a particular balance ID appears as either source or destination.

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    "query_by": "source,destination",
    "sort_by": "created_at:desc"
  }'

const response = await blnk.Search.search(
  {
    q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    query_by: "source,destination",
    sort_by: "created_at:desc",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
        QueryBy: "source,destination",
        SortBy: "created_at:desc",
    },
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    "query_by": "source,destination",
    "sort_by": "created_at:desc",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e")
        .queryBy("source,destination")
        .sortBy("created_at:desc"),
    "transactions"
);

Get recent high-value transactions

Find transactions above a certain amount threshold to monitor large money movements or flag suspicious activity.

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": "amount:>10000",
    "sort_by": "created_at:desc",
    "per_page": 50
  }'

const response = await blnk.Search.search(
  {
    q: "*",
    filter_by: "amount:>10000",
    sort_by: "created_at:desc",
    per_page: 50,
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "*",
        FilterBy: "amount:>10000",
        SortBy: "created_at:desc",
        PerPage: 50,
    },
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "*",
    "filter_by": "amount:>10000",
    "sort_by": "created_at:desc",
    "per_page": 50,
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("*")
        .filterBy("amount:>10000")
        .sortBy("created_at:desc")
        .perPage(50),
    "transactions"
);

Search transactions by date range

Retrieve all transactions that occurred within a specific time period for reporting or audit purposes. Use Unix timestamps for date filtering.

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": "created_at:[1704067200..1706745599]",
    "sort_by": "created_at:desc"
  }'

const response = await blnk.Search.search(
  {
    q: "*",
    filter_by: "created_at:[1704067200..1706745599]",
    sort_by: "created_at:desc",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "*",
        FilterBy: "created_at:[1704067200..1706745599]",
        SortBy: "created_at:desc",
    },
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "*",
    "filter_by": "created_at:[1704067200..1706745599]",
    "sort_by": "created_at:desc",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("*")
        .filterBy(
            "created_at:[1704067200..1706745599]"
        )
        .sortBy("created_at:desc"),
    "transactions"
);

Learn more about date filtering and Unix timestamps in our Filtering documentation.

Find rejected transactions

Filter transactions by status to identify failed payments that were rejected due to insufficient funds or validation errors.

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:=REJECTED",
    "sort_by": "created_at:desc"
  }'

const response = await blnk.Search.search(
  {
    q: "*",
    filter_by: "status:=REJECTED",
    sort_by: "created_at:desc",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "*",
        FilterBy: "status:=REJECTED",
        SortBy: "created_at:desc",
    },
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "*",
    "filter_by": "status:=REJECTED",
    "sort_by": "created_at:desc",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("*")
        .filterBy("status:=REJECTED")
        .sortBy("created_at:desc"),
    "transactions"
);

For advanced filtering with operators like :=, &&, and ranges, see our detailed Filtering guide.

Search by transaction type or description

Use full-text search to find transactions based on transaction type in metadata or descriptions for customer support.

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "payment",
    "query_by": "meta_data.transaction_type,description",
    "sort_by": "created_at:desc"
  }'

const response = await blnk.Search.search(
  {
    q: "payment",
    query_by: "meta_data.transaction_type,description",
    sort_by: "created_at:desc",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "payment",
        QueryBy: "meta_data.transaction_type,description",
        SortBy: "created_at:desc",
    },
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "payment",
    "query_by": "meta_data.transaction_type,description",
    "sort_by": "created_at:desc",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("payment")
        .queryBy("meta_data.transaction_type,description")
        .sortBy("created_at:desc"),
    "transactions"
);

Learn more about full-text search and field-specific queries in our Querying documentation.

Find transactions between specific accounts

Search for transactions that occurred between two particular balance IDs to track money flow or analyze trading patterns.

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": "source:=bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e && '\
'destination:=bln_86ba7976-499d-4282-955e-a7c2abf5db12",
    "sort_by": "created_at:desc"
  }'

const filterBy =
  "source:=bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e" +
  " && destination:=bln_86ba7976-499d-4282-955e-a7c2abf5db12";

const response = await blnk.Search.search(
  {
    q: "*",
    filter_by: filterBy,
    sort_by: "created_at:desc",
  },
  'transactions',
);

filterBy := "source:=bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e" +
    " && destination:=bln_86ba7976-499d-4282-955e-a7c2abf5db12"

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "*",
        FilterBy: filterBy,
        SortBy: "created_at:desc",
    },
    blnkgo.Transactions,
)

filter_by = (
  "source:=bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e"
  " && destination:=bln_86ba7976-499d-4282-955e-a7c2abf5db12"
)

response = blnk.search.search(
  {
    "q": "*",
    "filter_by": filter_by,
    "sort_by": "created_at:desc",
  },
  "transactions",
)

String filterBy =
    "source:=bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e"
        + " && destination:=bln_86ba7976-499d-4282-955e-a7c2abf5db12";

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("*")
        .filterBy(filterBy)
        .sortBy("created_at:desc"),
    "transactions"
);

2. Account management

Get balances above/below a threshold

Find all balances with amounts greater than or less than specific values for risk management or account monitoring.

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/balances" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "balance:>100000",
    "sort_by": "balance:desc"
  }'

const response = await blnk.Search.search(
  {
    q: "*",
    filter_by: "balance:>100000",
    sort_by: "balance:desc",
  },
  'balances',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "*",
        FilterBy: "balance:>100000",
        SortBy: "balance:desc",
    },
    blnkgo.Balances,
)

response = blnk.search.search(
  {
    "q": "*",
    "filter_by": "balance:>100000",
    "sort_by": "balance:desc",
  },
  "balances",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("*")
        .filterBy("balance:>100000")
        .sortBy("balance:desc"),
    "balances"
);

Fetch all balances belonging to an identity

Retrieve all balances associated with a specific identity ID to get a complete view of a user’s accounts and wallets.

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/balances" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "identity_id:=idt_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    "sort_by": "created_at:desc"
  }'

const response = await blnk.Search.search(
  {
    q: "*",
    filter_by:
      "identity_id:=idt_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    sort_by: "created_at:desc",
  },
  'balances',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "*",
        FilterBy: "identity_id:=idt_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
        SortBy: "created_at:desc",
    },
    blnkgo.Balances,
)

response = blnk.search.search(
  {
    "q": "*",
    "filter_by": "identity_id:=idt_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    "sort_by": "created_at:desc",
  },
  "balances",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("*")
        .filterBy(
            "identity_id:=idt_28f25ef6-2e0d-4fa6-891c-37fc409d654e"
        )
        .sortBy("created_at:desc"),
    "balances"
);

Search ledgers by name or metadata

Find specific ledgers using partial name matching or metadata filters to locate the right ledger for operations.

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/ledgers" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "customer savings",
    "query_by": "name",
    "sort_by": "created_at:desc"
  }'

const response = await blnk.Search.search(
  {
    q: "customer savings",
    query_by: "name",
    sort_by: "created_at:desc",
  },
  'ledgers',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "customer savings",
        QueryBy: "name",
        SortBy: "created_at:desc",
    },
    blnkgo.Ledgers,
)

response = blnk.search.search(
  {
    "q": "customer savings",
    "query_by": "name",
    "sort_by": "created_at:desc",
  },
  "ledgers",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("customer savings")
        .queryBy("name")
        .sortBy("created_at:desc"),
    "ledgers"
);

3. Customer support

Search identities by name or email

Find specific customer identities using partial name matching or email addresses for customer support and account verification.

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/identities" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "john doe",
    "query_by": "first_name,last_name,email",
    "sort_by": "created_at:desc"
  }'

const response = await blnk.Search.search(
  {
    q: "john doe",
    query_by: "first_name,last_name,email",
    sort_by: "created_at:desc",
  },
  'identities',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "john doe",
        QueryBy: "first_name,last_name,email",
        SortBy: "created_at:desc",
    },
    blnkgo.Identities,
)

response = blnk.search.search(
  {
    "q": "john doe",
    "query_by": "first_name,last_name,email",
    "sort_by": "created_at:desc",
  },
  "identities",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("john doe")
        .queryBy("first_name,last_name,email")
        .sortBy("created_at:desc"),
    "identities"
);

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.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Searchable collections

Quick start

Request parameters

Response structure

Common use cases

1. Transaction analysis

2. Account management

3. Customer support

Need help?

​Searchable collections

​Quick start

​Request parameters

​Response structure

​Common use cases

​1. Transaction analysis

​2. Account management

​3. Customer support

​Need help?

Searchable collections

Quick start

Request parameters

Response structure

Common use cases

1. Transaction analysis

2. Account management

3. Customer support

Need help?