How to filter results 🔍

Our API uses MongoDB-style query operators for filtering results, allowing you to perform powerful and flexible searches across all endpoints. Filters are applied using optional query parameters that follow MongoDB's query syntax.

Basic Filtering

To filter results, add query parameters to your request URL where the parameter name corresponds to a field in the resource schema.

For example, to filter transactions by amount, use the query parameter amount=value in your request:

https://api.cardda.com/v1/banking/transactions?amount=100

This returns all transactions with an amount of exactly 100.

MongoDB Query Operators

You can use MongoDB-style operators for more complex filtering. The value of any query parameter can be:

Simple Value Matching

• value - Exact match (e.g., amount=100)

Comparison Operators

• '{"$lt": value}' - Less than
• '{"$lte": value}' - Less than or equal to
• '{"$gt": value}' - Greater than
• '{"$gte": value}' - Greater than or equal to

Pattern Matching

• '{"$regex": "pattern"}' - Regular expression match

Array Operations

• '{"$in": ["value1", "value2"]}' - Match any value in the array

Nested Field Queries

• '{"nested_field": value}' - Query nested object fields
• '{"nested_field": {"$operator": value}}' - Apply operators to nested fields

Example Requests

# Get transactions greater than $500
https://api.cardda.com/v1/banking/transactions?amount={"$gt": 500}

# Get transactions with specific statuses
https://api.cardda.com/v1/banking/transactions?status={"$in": ["pending", "approved"]}

# Get transactions with amounts between $50 and $100
https://api.cardda.com/v1/banking/transactions?amount={"$gt": 50, "$lt": 100}

Logical OR Operations

Use the special $or parameter to combine multiple conditions with logical OR. The value should be an array of filter objects:

[
  {
    "status": {
      "$in": ["pending", "approved"]
    }
  },
  {
    "amount": {
      "$gt": 1000
    }
  }
]

Example request:

https://api.cardda.com/v1/banking/transactions?$or=[{"status": {"$in": ["pending", "approved"]}}, {"amount": {"$gt": 1000}}]

This returns transactions that are either pending/approved OR have an amount greater than $1000.

Logical AND Operations

For AND operations on the same field, combine multiple operators in a single query parameter:

# Get transactions between $50 and $100
https://api.cardda.com/v1/banking/transactions?amount={"$gt": 50, "$lt": 100}

For AND operations across different fields, simply use multiple query parameters:

# Get approved transactions over $100
https://api.cardda.com/v1/banking/transactions?status=approved&amount={"$gt": 100}

Important Notes

• All query parameter values using operators must be properly JSON-encoded strings
• Multiple query parameters are combined with logical AND by default
• Field names in filters must match the exact field names in the resource schema
• URL-encode special characters when necessary