Search Query and Filters

The Search API enables you to query records within a specified data type (scope). Use query parameters for text searches across multiple fields, or filters for precise matching on specific attributes.

Basic Search

A basic search requires the scope parameter and returns paginated results (30 per page by default) with newest items first.

curl https://api.omise.co/search?scope=charge \
  -u $OMISE_SECRET_KEY:

Query Parameter

The query parameter searches across scope-specific text attributes:

# Search for charges with "somchai" in searchable fields
curl https://api.omise.co/search?scope=charge&query=somchai \
  -u $OMISE_SECRET_KEY:

The query searches across multiple fields depending on the scope. For charges, it searches id, card_bank, card_name, description, failure_message, and metadata.

Filters Parameter

The filters parameter matches objects meeting specific conditions:

# Find charges of exactly 1000 THB
curl "https://api.omise.co/search?scope=charge&filters[amount]=1000&filters[currency]=THB" \
  -u $OMISE_SECRET_KEY:

Boolean Values

Boolean filters accept natural language equivalents:

True Values	False Values
yes	no
on	off
true	false

# Find captured charges
curl "https://api.omise.co/search?scope=charge&filters[captured]=yes" \
  -u $OMISE_SECRET_KEY:

Range Syntax

Use .. to specify ranges for numeric and date fields:

Numeric ranges:

# Find charges between 1000 and 5000 (in base currency units)
curl "https://api.omise.co/search?scope=charge&filters[amount]=1000..5000" \
  -u $OMISE_SECRET_KEY:

Date ranges:

# Find charges created in January 2025
curl "https://api.omise.co/search?scope=charge&filters[created]=2025/01/01..2025/01/31" \
  -u $OMISE_SECRET_KEY:

Relative date ranges:

Value	Description
today	Current day
yesterday	Previous day
this_week	Current week
last_week	Previous week
this_month	Current month
last_month	Previous month

# Find charges created this month
curl "https://api.omise.co/search?scope=charge&filters[created]=this_month" \
  -u $OMISE_SECRET_KEY:

Amount Units

For searching amount fields, use the base unit for a given currency (e.g., 100 for 100 THB), not the smallest unit/subunit (e.g., 10000 satang).

Additional Parameters

Expand Objects

Use expand=true to return ID fields as full objects:

curl "https://api.omise.co/search?scope=charge&expand=true" \
  -u $OMISE_SECRET_KEY:

Export Results

Use export=true with filter_type to create exports:

curl "https://api.omise.co/search?scope=charge&export=true&filter_type=monthly_captured" \
  -u $OMISE_SECRET_KEY:

Available filter types:

• monthly_captured - Captured charges for the month
• monthly_created - Created charges for the month
• monthly_date - Charges by date for the month

---

Searchable Scopes

charge

Search for charges and payments.

Filterable attributes:

Attribute	Type	Description
amount	integer	Charge amount in base currency units
authorized	boolean	Whether the charge is authorized
capture	boolean	Whether auto-capture is enabled
captured	boolean	Whether the charge has been captured
captured_at	datetime	When the charge was captured
credit_card_brand	string	Card brand (visa, mastercard, etc.)
card_last_digits	string	Last 4 digits of the card
created	datetime	When the charge was created
currency	string	Currency code
disputed	boolean	Whether the charge is disputed
failure_code	string	Failure code if failed
fraud	boolean	Whether flagged for fraud
is_installment	boolean	Whether it's an installment payment
refunded	boolean	Whether the charge has been refunded
refund_amount	integer	Total refunded amount
scheduled	boolean	Whether it's a scheduled charge
source_of_fund	string	Source of funds
source_type	string	Payment source type
status	string	Charge status
voided	boolean	Whether the charge was voided
installment_terms	integer	Number of installment terms

Queryable attributes: id, card_bank, card_name, description, failure_message, metadata

customer

Search for customer records.

Filterable attributes:

Attribute	Type	Description
created	datetime	When the customer was created

Queryable attributes: id, description, email, metadata

dispute

Search for dispute records.

Filterable attributes:

Attribute	Type	Description
amount	integer	Disputed amount
card_first_digits	string	First 6 digits of the card
card_last_digits	string	Last 4 digits of the card
charge_id	string	Associated charge ID
closed_at	datetime	When the dispute was closed
created	datetime	When the dispute was created
currency	string	Currency code
fraud	boolean	Whether flagged as fraud
status	string	Dispute status

Queryable attributes: id, card_brand, card_id, card_name, metadata, message, reason_code, reason_message

link

Search for payment links.

Filterable attributes:

Attribute	Type	Description
amount	integer	Link amount
created	datetime	When the link was created
currency	string	Currency code
multiple	boolean	Whether multiple payments allowed
used	boolean	Whether the link has been used
used_at	datetime	When the link was used

Queryable attributes: id, description, link_reference, title

receipt

Search for receipt records.

Filterable attributes:

Attribute	Type	Description
created	datetime	When the receipt was created

Queryable attributes: id

recipient

Search for transfer recipients.

Filterable attributes:

Attribute	Type	Description
active	boolean	Whether the recipient is active
activated_at	datetime	When the recipient was activated
bank_last_digits	string	Last digits of bank account
created	datetime	When the recipient was created
deleted	boolean	Whether the recipient is deleted
failure_code	string	Verification failure code
type	string	Recipient type (individual/corporation)
verified	boolean	Whether the recipient is verified
verified_at	datetime	When the recipient was verified

Queryable attributes: id, bank_name, bank_brand, description, email, metadata, name, tax_id

refund

Search for refund records.

Filterable attributes:

Attribute	Type	Description
amount	integer	Refund amount
card_first_digits	string	First 6 digits of the card
card_last_digits	string	Last 4 digits of the card
charge_id	string	Associated charge ID
created	datetime	When the refund was created
status	string	Refund status
voided	boolean	Whether the refund was voided

Queryable attributes: id, card_bank, card_brand, card_id, card_name, charge_description, currency, metadata

transfer

Search for transfer records.

Filterable attributes:

Attribute	Type	Description
amount	integer	Transfer amount
created	datetime	When the transfer was created
currency	string	Currency code
fee	integer	Transfer fee
paid	boolean	Whether the transfer has been paid
paid_at	datetime	When the transfer was paid
sent	boolean	Whether the transfer has been sent
sent_at	datetime	When the transfer was sent

Queryable attributes: id, bank_name, bank_brand, failure_code, failure_message, metadata, recipient_email, recipient_id, recipient_name, transaction_id

transaction

Search for transaction records.

Filterable attributes:

Attribute	Type	Description
amount	integer	Transaction amount
created	datetime	When the transaction was created
currency	string	Currency code
hold_until	datetime	Hold expiration date
kind	string	Transaction type

Queryable attributes: id, record_id

charge_schedule

Search for charge schedules (recurring payments).

Filterable attributes:

Attribute	Type	Description
status	string	Schedule status
active	boolean	Whether the schedule is active
amount	integer	Scheduled charge amount
created	datetime	When the schedule was created
card_last_digits	string	Last 4 digits of the card

Queryable attributes: recurrence_id, currency, description, customer_email, card_brand, card_bank, card_name

transfer_schedule

Search for transfer schedules.

Filterable attributes:

Attribute	Type	Description
status	string	Schedule status
active	boolean	Whether the schedule is active
created	datetime	When the schedule was created

Queryable attributes: recurrence_id, recipient_name

---

Examples

Find High-Value Captured Charges

curl "https://api.omise.co/search?scope=charge&filters[amount]=10000..&filters[captured]=true&filters[created]=this_month" \
  -u $OMISE_SECRET_KEY:

Find Customers by Email Domain

curl "https://api.omise.co/search?scope=customer&query=@company.com" \
  -u $OMISE_SECRET_KEY:

Find Pending Disputes

curl "https://api.omise.co/search?scope=dispute&filters[status]=pending" \
  -u $OMISE_SECRET_KEY:

Find Failed Transfers

curl "https://api.omise.co/search?scope=transfer&filters[paid]=false&query=failure" \
  -u $OMISE_SECRET_KEY:

---

FAQ

Can I combine query and filters in the same request?

Yes, you can use both query and filters parameters together. The query searches text fields while filters match exact attribute values. Results must match both conditions.

What is the difference between query and filters?

The query parameter performs text search across multiple fields (like a search box), while filters match exact values on specific attributes. Use query for fuzzy text matching and filters for precise filtering.

How do I search within metadata?

Use the query parameter to search metadata content. For example, query=order123 will find records where metadata contains "order123". Note that metadata is only queryable, not filterable.

What date formats are supported?

Dates can be specified as YYYY/MM/DD, YYYY-MM-DD, or using relative values like today, this_week, this_month. Ranges use the .. syntax: 2025/01/01..2025/01/31.

Why are my amount searches not returning expected results?

Remember to use base currency units, not subunits. For THB, search for 1000 to find 1000 THB charges, not 100000 (which would be in satang).

How many results are returned per page?

The Search API returns 30 results per page by default. Use pagination parameters to navigate through larger result sets.

---

Try it Out

Test the Search API interactively using the Universal Search page. Enter your API key, select a scope, and experiment with different query and filter combinations.

Quick test examples:

# Search charges with a query
curl "https://api.omise.co/search?scope=charge&query=test" \
  -u $OMISE_SECRET_KEY:

# Filter by status and date range
curl "https://api.omise.co/search?scope=charge&filters[status]=successful&filters[created]=this_month" \
  -u $OMISE_SECRET_KEY:

# Search customers by email
curl "https://api.omise.co/search?scope=customer&query=@gmail.com" \
  -u $OMISE_SECRET_KEY:

---

Related Resources

• Universal Search - Interactive API testing
• Charges API
• Customers API
• Pagination