> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Querying Parameters

> Learn how to use the query field.

## Overview

The querying parameters `q` and `query_by` work together to control what data you search for and which fields to search in. These parameters enable you to perform full-text searches, exact matches, and wildcard queries across your ledger data.

The `q` parameter is required in all search requests. The `query_by` parameter is required when searching for specific terms, and optional only when using the wildcard `*`.

***

## Quick start

Here's a basic search query that demonstrates both parameters:

<CodeGroup>
  ```bash cURL theme={"system"}
  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"
    }'
  ```

  ```json Response theme={"system"}
  {
    "found": 3,
      "hits": [
          {
              "document": {
                  "amount": 5000,
          "created_at": 1720363463,
                  "currency": "USD",
          "description": "Payment for services",
          "destination": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
          "source": "bln_86ba7976-499d-4282-955e-a7c2abf5db12",
          "status": "APPLIED",
                  "transaction_id": "txn_4c86b65e-8249-4b3b-8000-b907d32f9a9f"
              },
              "highlights": [
                  {
            "field": "destination",
            "matched_tokens": ["bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e"],
            "snippet": "<mark>bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e</mark>"
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

***

## Query parameters

### Exact text search

Search for specific text or IDs by specifying the fields to search in:

```bash theme={"system"}
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"
  }'
```

### Wildcard search

Use `*` to return all records (only case where `query_by` is optional):

```bash theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/balances" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*"
  }'
```

### Multi-word search

Search for multiple words across specified fields:

```bash theme={"system"}
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 services",
    "query_by": "description"
  }'
```

<Warning>
  Multi-word searches require ALL words to be present in the document. For "payment services", both "payment" AND "services" must exist in the specified fields.
</Warning>

### Single vs multiple fields

Search in one field or across multiple fields using comma separation:

```bash theme={"system"}
# Single field
{
  "q": "john",
  "query_by": "first_name"
}

# Multiple fields
{
  "q": "john doe",
  "query_by": "first_name,last_name,email"
}
```

### Metadata search

<Info> Available in version 0.11.0 and later. </Info>

Search within metadata or nested objects using dot notation:

```bash theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "transfer",
    "query_by": "meta_data.transaction_type,description"
  }'
```

***

## Common patterns

<Steps>
  <Step title="Search for a specific balance's transactions">
    This finds all transactions where the specified balance ID appears as either source or destination.

    ```bash theme={"system"}
    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"
      }'
    ```
  </Step>

  <Step title="Find customers by name or email">
    This searches for "alice" across name and email fields, useful for customer support.

    ```bash theme={"system"}
    curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/identities" \
      -H "X-Blnk-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "alice",
        "query_by": "first_name,last_name,email"
      }'
    ```
  </Step>

  <Step title="Find transactions by description keywords">
    This finds transactions containing "refund" in their description or reference fields.

    ```bash theme={"system"}
    curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
      -H "X-Blnk-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "refund",
        "query_by": "description,reference"
      }'
    ```
  </Step>
</Steps>

***

## Best practices

* **Be specific with fields**: Target relevant fields in `query_by` for better performance.
* **Validate field names**: Invalid fields in `query_by` may return unexpected results.

***

## 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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).

***

<Tip>
  **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 →](https://www.blnkfinance.com/products/cloud)
</Tip>