Admin API | Docs

# Expanding Responses Some endpoints are able to return more data than they normally do by expanding their response. When this is possible the endpoint will specify the `expand` field and will document which fields can be expanded. The expand field takes an array of string field names that identify which fields you wish to expand. ## Expanding Fields To expand a single field, you may specify it as part of the query. For example: ```text /example-endpoint?expand[]=bar ``` This will cause the `bar` key and its value to be included in the response. If `bar` itself has expandable fields, see [path expands](#section/Expanding-Responses/Path-Expands). ## Path Expands If the field you wish to expand is not a top level key within the response, you may specify it using dot notation. For example: ```text /example-endpoint?expand[]=foo.bar ``` If `foo` itself is not an expandable field, this will work like a normal field expand. The `bar` key and its value will be included in the response nested under the `foo` key. If `foo` is an expandable field, see [nested expands](#section/Expanding-Responses/Nested-Expands). ## Expanding Multiple Fields To expand more than one field, you may add additional expands to the query. For example: ```text /example-endpoint?expand[]=bar&expand[]=baz ``` ## Nested Expands If you are already expanding a field, `foo`, and it has its own expandable field(s), `bar`, you may additionally expand bar as follows. ```text /example-endpoint?expand[]=foo&expand[]=foo.bar ``` The `foo` key and its value will be included in the response. Additionally, The `bar` key and its value will be included in the response nested under the `foo` key. If you wish to expand the `bar` key, but are not interested in the other keys on `foo`, see [granular expands](#section/Expanding-Responses/Granular-Expands). ## Granular Expands If `foo` is an expandable field whose keys you are not interested in except for its own expandable field `bar`, you may do the following. ```text /example-endpoint?expand[]=foo.bar ``` The `foo` key will exist, but its value will only have the `bar` key, discluding all other sibling keys you did not explicitly ask for. # Search Query Language Some endpoints specify a `search` parameter. The value of this parameter must be a string that contains a valid query as defined by this search query language. **IMPORTANT NOTICE** Every list-type endpoint that accepts a `search` parameter requires that the search parameter is supplied, and furthermore that an organization PRN clause is provided in the search like so: `organization_prn:'value'`. ## Queries A query consists of at least one and at most five clauses joined by the `and` keyword. For example: ```text inserted_at>='2023-01-01T00:00:00Z' and description~'east blue' ``` ## Clauses A clause consists of a key, an operator, and a value. For example: ```text inserted_at>='2023-01-01T00:00:00Z' ``` ## Keys When performing a search, the set of valid keys is defined by the relevant endpoint's `search` parameter's documentation. ## Operators Each key an endpoint specifies as searchable will be associated with a set of operators that are valid to use with it. Below are all possible operators and their associated operation: |Keyword|Operation| |-|-| |`:`|equals (case-sensitive)| |`-`|substring (case-insensitive)| |`~`|substring (case-sensitive)| |`<`|less than| |`<=`|less than or equal to| |`>`|greater than| |`>=`|greater than or equal to| ## Values Each key will specify which type of value it acepts. ### String You must use single quotes when supplying a string. You can escape single quotes inside of single quotes with a backslash (`\`). For example: ```text summary~'zoro\'s three sword style' ``` ### Boolean Boolean values are supplied either `true` or `false` without single quotes. For example: ```text archived:true ``` ### Date-Time You must use single quotes when supplying a date-time and you must use the following representation: `'[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z'`. The timezone is always UTC. For example: ```text inserted_at:'2023-01-01T00:00:00Z' ``` ### Numeric Numeric values are supplied as-is without single quotes. For example: ```text berries:100000000 ```