Search Query and Filters

The Search API allows you to search records within a given type (scope) of data.

Usage

The search scope is required. A simple search looks like this:

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge"

The above example returns all charges on your account with the most recently created charges appearing first. The results are paginated, and response is the first page with a default of 30 results per page. See Search API for all accepted parameters, object structure, and more examples.

To narrow your search, add the query and filters parameters. When both query and filters are supplied, the result is the combined set.

Queries

When the query parameter is supplied, returned objects are those where the query string is found across one of a set of attributes specific to that scope.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "query=somchai"

The above example returns charges where the string somchai is found across one of the query attributes for search (for example, customer_name).

Filters

When the filters parameter is supplied, returned objects are those which match the conditions set by the filter object.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[amount]=1000" \
     -d "filters[currency]=USD"

The above example returns charges where the amount field is exactly 1000 USD.

For searching amount fields, use the commonly accepted currency unit, not the smallest currency unit. So, a charge created with amount=100000 and currency=USD is searchable as filters[amount]=1000.

Booleans

For boolean filters, some natural language equivalents are acceptable in place of true and false.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[captured]=yes"
curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[captured]=on"
curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[captured]=no"
curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[captured]=off"

Ranges

For numeric and date filters, you can add ranges. Some natural language equivalents (for example, this_month) are acceptable.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[amount]=1000..2000"
curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[created]=2019/01/01..2019/12/31"
curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=charge" \
     -d "filters[created]=this_month"

The first example conducts a search for charges where the amount is between 1000 and 2000 (USD, THB, JPY, etc.). The second example conducts a search for charges where the creation date is within the year 2019. The third example conducts a search for charges where the creation date is this month.

Expanding ID Fields

Across the API, certain attributes can return either an identifier, the default, or the object itself. Use the expand parameter to return these attributes as objects.

curl https://api.omise.co/search \
     -X GET \
     -u $OMISE_SECRET_KEY: \
     -d "scope=refund" \
     -d "expand=true"

Available Queries and Filters

Charge

Use scope=charge to search for Charge records. The following queries and filters are specific to this scope.

Filters

Search for a specific value using the following keys in a filters object.

Key Description
amount Charge amount in main unit of charge currency. For example, use 1000 for 1000 THB.
authorized Whether charge has been authorized.
capture Whether charge is set to be automatically captured (paid).
captured Whether charge has been captured (paid).
captured_at UTC datetime of charge capture (payment) in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
card_last_digits Last four (4) digits of card number.
created UTC datetime of charge creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
currency Currency for charge as three-letter ISO 4217 code.
customer_present Whether charge has a customer attached.
disputed Whether charge is disputed.
failure_code Failure code if status == failed. See testing for possible codes.
is_installment Whether charge is installment.
refunded Charge amount refunded.
refund_amount Amount for refund in common currency unit. For example, use 1000 for 1000 THB.
reversed Whether charge authorization has been reversed.
safe Whether charge is safe. A safe charge is one which has successfully passed our fraud protection process.
scheduled Whether charge is scheduled.
source_of_fund Payment mode. One of card, offsite, or offline.
source_type Payment source type. Value can be one of the following (depending on account and country):
  • alipay
  • barcode_alipay
  • bill_payment_tesco_lotus
  • econtext
  • installment_bay
  • installment_bbl
  • installment_first_choice
  • installment_kbank
  • installment_ktc
  • internet_banking_bay
  • internet_banking_bbl
  • internet_banking_ktb
  • internet_banking_scb
  • points
  • truemoney
See installments for allowed values.
status Charge status. One of failed, expired, pending, reversed or successful.
voided Whether, in the case of a refund, charge was voided instead. Charges are voided if refund is processed before settlement time.
installment_terms Installment term in months. See installments for allowed values (type=installment_*).

Queries

Search across the following keys using a query string.

Key Description
id The charge identifier matching /chrg(_test)?_[0-9a-z]+/.
card_bank Card bank name. Note: derived from issuer identification number (IIN); may not be accurate.
card_brand Card brand (e.g. Visa, Mastercard).
card_id The card identifier matching /card(_test)?_[0-9a-z]+/.
card_name Card owner name.
customer_description Customer description.
customer_email Customer email address.
customer_id The customer identifier matching /cust(_test)?_[0-9a-z]+/.
description Charge description.
failure_message Message describing the failure if status == failed.
metadata Custom metadata (e.g. {"answer": 42}) for charge.

Customer

Use scope=customer to search for Customer records. The following queries and filters are specific to this scope.

Filters

Search for a specific value using the following keys in a filters object.

Key Description
created UTC datetime of customer creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Queries

Search across the following keys using a query string.

Key Description
id The customer identifier matching /cust(_test)?_[0-9a-z]+/.
description Customer description.
email Customer email address.
metadata Custom metadata (e.g. {"answer": 42}) for customer.

Dispute

Use scope=dispute to search for Dispute records. The following queries and filters are specific to this scope.

Filters

Search for a specific value using the following keys in a filters object.

Key Description
amount Dispute amount in smallest unit of dispute currency.
card_first_digits First six (6) digits of the card number: the issuer identification number (IIN).
card_last_digits Last four (4) digits of card number.
charge_id The charge identifier matching /chrg(_test)?_[0-9a-z]+/.
closed_at UTC datetime of dispute closure (i.e. status changed to won or lost) of the dispute in ISO 8601 format.
created UTC datetime of dispute creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
currency Currency for dispute as three-letter ISO 4217 code.
status The dispute status. One of open, pending, won or lost. (note: won and lost disputes are retrievable using the /disputes/closed endpoint).

Queries

Search across the following keys using a query string.

Key Description
id The dispute identifier matching /dspt(_test)?_[0-9a-z]+/.
card_brand Card brand (e.g. Visa, Mastercard).
card_id The card identifier matching /card(_test)?_[0-9a-z]+/.
card_name Card owner name.
metadata Custom metadata (e.g. {"answer": 42}) for dispute.
message Explanation for dispute.
reason_code Dispute reason code.
reason_message Dispute message associated with the dispute reason code.

Use scope=link to search for Link records. The following queries and filters are specific to this scope.

Filters

Search for a specific value using the following keys in a filters object.

Key Description
amount Link amount in main unit of link currency. For example, use 1000 for 1000 THB.
created UTC datetime of link creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
currency Currency for link as three-letter ISO 4217 code.
multiple Whether link is able to be used more than once.
used Whether single-use link (multiple=false) was used.
used_at UTC datetime of the usage of the link in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). Single-use links only.

Queries

Search across the following keys using a query string.

Key Description
id The link identifier matching /link(_test)?_[0-9a-z]+/.
description Link description.
link_reference URI of link.
title Link title.

Recipient

Use scope=recipient to search for Recipient records. The following queries and filters are specific to this scope.

Filters

Search for a specific value using the following keys in a filters object.

Key Description
active Whether recipient is active.
activated_at UTC datetime of the activation of the recipient in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
bank_last_digits Last four (4) digits of bank account number.
created UTC datetime of recipient creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
deleted Whether recipient is deleted.
failure_code Recipient creation failure code. One of name_mismatch, account_not_found, or bank_not_found.
type Recipient type. One of individual or corporation.
verified Whether recipient is verified.
verified_at UTC datetime of the verification of the recipient in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Queries

Search across the following keys using a query string.

Key Description
id The recipient identifier matching /recp(_test)?_[0-9a-z]+/.
bank_name Bank account holder name.
bank_brand Bank account brand (Thailand and Singapore only).
description Recipient description.
email Recipient email address.
metadata Custom metadata (e.g. {"answer": 42}) for recipient.
name Recipient name.
tax_id Recipient tax ID.

Refund

Use scope=refund to search for Refund records. The following queries and filters are specific to this scope.

Filters

Search for a specific value using the following keys in a filters object.

Key Description
amount Refund amount in smallest unit of charge currency.
card_first_digits First 6 digits of the card number: the issuer identification number (IIN).
card_last_digits Last four (4) digits of card number.
charge_id The charge identifier matching /chrg(_test)?_[0-9a-z]+/.
created UTC datetime of refund creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
status Status of the refund.
voided Whether refunded charge was voided instead. Charges are voided if refund is processed before settlement time.

Queries

Search across the following keys using a query string.

Key Description
id The refund identifier matching /rfnd(_test)?_[0-9a-z]+/.
card_bank Card bank name. Note: derived from issuer identification number (IIN); may not be accurate.
card_brand Card brand (e.g. Visa, Mastercard).
card_id The card identifier matching /card(_test)?_[0-9a-z]+/.
card_name Card owner name.
charge_description Charge description.
currency Currency for refund as three-letter ISO 4217 code.
metadata Custom metadata (e.g. {"answer": 42}) for refund.

Transfer

Use scope=transfer to search for Transfer records. The following queries and filters are specific to this scope.

Filters

Search for a specific value using the following keys in a filters object.

Key Description
amount Transfer amount in smallest unit of transfer currency.
created UTC datetime of transfer creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
currency Currency for transfer as three-letter ISO 4217 code.
deleted Whether transfer is deleted.
fee Omise transfer fee.
paid Whether transfer was paid.
paid_at UTC datetime of the transfer payment in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
sent Whether transfer was sent.
sent_at UTC datetime of the transfer send event in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Queries

Search across the following keys using a query string.

Key Description
id The transfer identifier matching /trsf(_test)?_[0-9a-z]+/.
bank_name Bank account holder name.
bank_brand Bank account brand (Thailand and Singapore only).
failure_code Failure code for transfer. One of insufficient_balance, invalid_recipient, transfers_suspended, transfer_deleted, transfer_sent, or transfer_failed.
failure_message Message describing the failure if failure_code exists.
metadata Custom metadata (e.g. {"answer": 42}) for transfer.
recipient_email Recipient email address.
recipient_id Recipient identifier to which the transfer was sent.
recipient_name Name of recipient to which transfer was sent.
transaction_id The transaction identifier matching /trxn(_test)?_[0-9a-z]+/.