Search

The Arta API supports flexible search functionality across multiple resources, including Shipments, Requests, Hosted Sessions, Tags, and others. Using the search query parameter, you can construct structured queries to filter results based on specific criteria.

Key features of the search functionality include:

  • Support for negation, wildcards, numeric filters, and date comparisons.
  • Each search query consists of one or more clauses, where each clause contains a field, an operator, and a value.

  • Clauses operating on the same field are combined using OR logic, while clauses across different fields are combined using AND logic.

  • Use quotation marks to keep multi-word search terms together.

This allows for powerful and precise filtering to retrieve the exact data you need from the API.

Syntax and operators

The following table lists the operators and syntax that you can use to construct a search query clause.

Operator Usage Description Examples
: field:value Exact match operator (case insensitive) status:pending returns records where the status is pending
* value* Use an asterisk (wildcard operator) at the end of a term to match fields that start with the fragment art* returns records that match "arta" and "artist" but not "smart"
* *value Use an asterisk at the start of a term to match fields that end with the fragment *art returns "smart" but not "martian"
- -field:value Returns records that don’t match the clause -status:pending returns records that do not have a status of pending
>, <, = field:<value, field:>value, field:>=value, field:<=value Greater than/less than operators created-at:<=2021-01-01 returns records from the beginning of time through January 1, 2021
.. field:value1..value2 Filters for values within a given range where the first number is the lowest value and the second is the highest created-at:2021-05-01..2021-05-15 returns records where the created_at field is between May 1, 2021 and May 15, 2021

Hosted Session search fields

Field Type
created-at date
destination-address-line-1 string
destination-city string
destination-contacts-emails string
destination-contacts-names string
destination-contacts-phone-numbers string
destination-country string
destination-postal-code string
destination-region string
insurance string
internal-reference string
object-creators string
object-descriptions string
object-internal-references string
object-public-references string
object-titles string
origin-address-line-1 string
origin-city string
origin-contacts-emails string
origin-contacts-names string
origin-contacts-phone-numbers string
origin-country string
origin-postal-code string
origin-region string
public-reference string
quote-type string
shipping-notes string
shortcode string
status string
type string
tags string

Request search fields

Field Type
bookable string
created-at date
destination-address-line-1 string
destination-city string
destination-contacts-emails string
destination-contacts-names string
destination-contacts-phone-numbers string
destination-country string
destination-postal-code string
destination-region string
hosted-session string
internal-reference string
object-creators string
object-descriptions string
object-internal-references string
object-public-references string
object-titles string
origin-address-line-1 string
origin-city string
origin-contacts-emails string
origin-contacts-names string
origin-contacts-phone-numbers string
origin-country string
origin-postal-code string
origin-region string
public-reference string
quote-type string
shipping-notes string
shortcode string
status string
tags string

Shipment search fields

Field Type
created-at date
destination-address-line-1 string
destination-city string
destination-contacts-emails string
destination-contacts-names string
destination-contacts-phone-numbers string
destination-country string
destination-postal-code string
destination-region string
eei-form-status string
hosted-session string
internal-reference string
object-creators string
object-descriptions string
object-internal-references string
object-public-references string
object-titles string
origin-address-line-1 string
origin-city string
origin-contacts-emails string
origin-contacts-names string
origin-contacts-phone-numbers string
origin-country string
origin-postal-code string
origin-region string
public-reference string
quote-type string
request-shortcode string
shipping-notes string
shortcode string
status string
tags string
total numeric
total-currency string
tracking-numbers string

Tag search fields

Field Type
color string
description string
is_active string
name string