# Search Assets by Name, Custom Field or Tag

> Find Assets by name, custom field value or tag, then narrow the list by type, status, Storage Location or reservation dates.

This is the Markdown copy of https://api.exhibitday.com/Help/V1?guide=search-assets for AI tools. Code examples are in curl, JavaScript, Python and C#; the help page shows all 8 languages, and https://api.exhibitday.com/llms-full.txt has the complete reference in one file. Index of all pages: https://api.exhibitday.com/llms.txt

Find Assets by name, custom field value or tag, then narrow the list by type, status, Storage Location or reservation dates.

Example use case

Before a show, you want every Active banner, the Assets that belong to your Trade Show Kit, the ones nobody has added to a kit yet, and everything tagged Europe.

What you'll end up with

The Assets that match your search, with the IDs you need to check availability or reserve them.

Before you start

Have a workspace API key. To search a custom field, know the name of a text or dropdown Asset field your workspace uses.

Good to know

The list includes Active and Archived Assets unless you filter by status. An Asset must match every filter you send.

## At a glance

Time to try

About 10 minutes

Effect on your data

Read-only

Endpoints

2

The requests only read Assets and your Asset custom fields. They change nothing.

- [`GET /v1/assets`](https://api.exhibitday.com/Help/V1?epf=5#get-v1-assets)
- [`GET /v1/references/asset_custom_fields`](https://api.exhibitday.com/Help/V1?epf=3#get-v1-references-asset_custom_fields)

## How it works

1. Search Assets by part of their name.
2. Look up a custom field's `id`, then search by the value saved in that field, or find Assets with nothing saved in it.
3. Search by tag, add the list's other filters, and read every page.

## How search matching works

- Searches ignore letter case, accents and spaces before or after your text. `cafe`, `Café` and `CAFE` find the same Assets.
- `%`, `_` and `[` match themselves. Search for them like any other character.
- A blank name or tag search is ignored, so it doesn't narrow the list.
- The name search finds your text anywhere in the Asset name.
- The tag filter matches one whole tag.
- A custom-field search matches the whole saved value, unless you ask for part of it with `contains`. An empty value finds Assets with nothing saved in that field.

## Search your Assets

The custom-field examples use a text field called Kit with the ID `45678`. Use your own field ID from Step 2.

## Step 1: Search by part of the Asset name

Find Active Assets with `banner` anywhere in the name. The later steps add `$return_asset_lites=true` to keep each result short.

```bash
curl -X GET "https://api.exhibitday.com/v1/assets?filter_by_asset_name_contains_text=banner&filter_by_asset_status_id=1&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

**Example response (shortened)**

```json
{
  "records_found": 1,
  "total_records": 1,
  "has_more": false,
  "list_data": [
    {
      "id": 12345,
      "asset_type_id": 1,
      "asset_status": "Active",
      "name": "Display stand"
    }
  ]
}
```

**Check:** `asset_type_id` is `1` for a Single-Unit Capital Asset and `2` for a Collateral / Multi-Quantity Item. Leave out `filter_by_asset_status_id` to include Archived Assets too.

## Step 2: Find the field you want to search

List your Asset custom fields. Pick the one to search by its `name`, the name you see on the Asset page.

```bash
curl -X GET "https://api.exhibitday.com/v1/references/asset_custom_fields" -H "Authorization: Bearer YOUR_API_KEY"
```

**Example response (shortened)**

```json
{
  "records_found": 1,
  "list_data": [
    {
      "id": 45678,
      "name": "Kit",
      "is_multi_line": false,
      "options": null,
      "is_hidden": false,
      "is_filterable": true
    }
  ]
}
```

**Check:** Use a field whose `is_filterable` is true. Text and dropdown fields can be searched, hidden ones included. Keep its `id`.

## Step 3: Search by a custom field value

Send the field `id` and the value. By default the whole saved value must match, so this finds Assets whose Kit is `Trade Show Kit`.

```bash
curl -X GET "https://api.exhibitday.com/v1/assets?filter_by_custom_field_value_setting_id=45678&filter_by_custom_field_value_setting_value=Trade%20Show%20Kit&%24return_asset_lites=true&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

To match part of a saved value, add `filter_by_custom_field_value_setting_match=contains`. This finds `Trade Show Kit`, `Demo Kit` and `Kit B`.

```bash
curl -X GET "https://api.exhibitday.com/v1/assets?filter_by_custom_field_value_setting_id=45678&filter_by_custom_field_value_setting_value=kit&filter_by_custom_field_value_setting_match=contains&%24return_asset_lites=true&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

**Check:** For a dropdown field, send one of its `options`. Asset Lite results leave out custom field values. Leave out `$return_asset_lites` to see each Asset's `custom_fields`.

## Step 4: Find Assets with no value in a field

Send the field `id` without a value to find Assets where nothing is saved in that field yet. Sending an empty value does the same.

```bash
curl -X GET "https://api.exhibitday.com/v1/assets?filter_by_custom_field_value_setting_id=45678&%24return_asset_lites=true&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

**Check:** These are the Assets to fill in. A dropdown field's default choice isn't a saved value, so an Asset where nobody picked a choice appears here.

## Step 5: Search by tag

Find Assets that have one whole tag.

```bash
curl -X GET "https://api.exhibitday.com/v1/assets?filter_by_asset_tag=Europe&%24return_asset_lites=true&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

**Check:** `Eur` doesn't match `Europe`, so send the whole tag. To find Assets with any of several tags, send one request per tag and combine the IDs.

## Step 6: Narrow the list and read every page

Add any of the Assets list's other filters. They work together with your searches. This request asks for the second page of Active Collateral, sorted by name.

```bash
curl -X GET "https://api.exhibitday.com/v1/assets?filter_by_asset_type_id=2&filter_by_asset_status_id=1&%24result_sort=name_asc&%24return_asset_lites=true&%24limit=50&%24offset=50" -H "Authorization: Bearer YOUR_API_KEY"
```

Other filters you can add:

| To find | Send |
| --- | --- |
| Single-Unit Capital Assets, or Collateral / Multi-Quantity Items | `filter_by_asset_type_id=1`, or `2` |
| Active or Archived Assets | `filter_by_asset_status_id=1`, or `2` |
| Capital Assets with one default Storage Location | `filter_by_default_storage_location_id` (IDs from `GET /v1/assets/storage_locations`) |
| Assets with a checkout date (Capital) or Reservation Date (Collateral) in a range | `filter_by_reservation_date_greater_than_or_equal_to` and `filter_by_reservation_date_smaller_than_or_equal_to`, with `filter_by_asset_type_id` |
| Capital Assets reserved for any part of a period | `filter_by_reservation_overlaps_start_date` and `filter_by_reservation_overlaps_end_date`, with `filter_by_asset_type_id=1` |
| Capital Assets returning in a date range | `filter_by_reservation_return_date_greater_than_or_equal_to` and `filter_by_reservation_return_date_smaller_than_or_equal_to` |
| Your system's ID in an integration field | `filter_by_integration_metadata_field_1` (fields 1 to 5) |
| A different order | `$result_sort`: `name_asc` (the default), `name_desc`, `create_timestamp_asc`, `create_timestamp_desc`, `id_asc` or `id_desc` |

**Check:** Send dates as `YYYY-MM-DD`. Reservation filters choose which Assets match. To see what's free on your dates, check availability instead.

**Check:** Start with `$offset=0`. While `has_more` is true, ask for the next page with the same filters and sort, and add 50 to `$offset`. `total_records` counts every matching Asset.

## Try it

## Before running the example

| Value | What to put in it |
| --- | --- |
| `YOUR_API_KEY` | Your workspace API key. Keep it out of shared code and logs. |
| `filter_by_asset_name_contains_text` | Part of an Asset name in your workspace. The example uses `banner`. |
| `$limit` and `$offset` | The example reads up to 50 matches starting at offset 0. |

**Note.** This example only reads data. It lists Active Assets whose name contains `banner`.

Copy the complete example in your language and run it. To try another search, change the request to match one of the steps above.

## Complete example program

Code Samples

```bash
curl -X GET "https://api.exhibitday.com/v1/assets?filter_by_asset_name_contains_text=banner&filter_by_asset_status_id=1&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript
const response = await fetch("https://api.exhibitday.com/v1/assets?" + new URLSearchParams({ "filter_by_asset_name_contains_text": "banner", "filter_by_asset_status_id": "1", "$limit": "50", "$offset": "0" }), {
  method: "GET",
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();
console.log(response.status, data);
```

```python
import requests

response = requests.get(
    "https://api.exhibitday.com/v1/assets",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"filter_by_asset_name_contains_text": "banner", "filter_by_asset_status_id": "1", "$limit": "50", "$offset": "0"},
)
print(response.status_code, response.json())
```

```csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
var response = await client.GetAsync("https://api.exhibitday.com/v1/assets?filter_by_asset_name_contains_text=banner&filter_by_asset_status_id=1&%24limit=50&%24offset=0");
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
```

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ExhibitDayExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.exhibitday.com/v1/assets?filter_by_asset_name_contains_text=banner&filter_by_asset_status_id=1&%24limit=50&%24offset=0"))
            .header("Authorization", "Bearer YOUR_API_KEY")
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

```php
<?php
$curl = curl_init('https://api.exhibitday.com/v1/assets?filter_by_asset_name_contains_text=banner&filter_by_asset_status_id=1&%24limit=50&%24offset=0');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($curl);
if ($response === false) {
    throw new RuntimeException(curl_error($curl));
}
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . PHP_EOL . $response;
curl_close($curl);
```

```ruby
require 'net/http'
require 'uri'

uri = URI('https://api.exhibitday.com/v1/assets?filter_by_asset_name_contains_text=banner&filter_by_asset_status_id=1&%24limit=50&%24offset=0')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(request)
end
puts "#{response.code} #{response.body}"
```

```go
package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    request, err := http.NewRequest("GET", "https://api.exhibitday.com/v1/assets?filter_by_asset_name_contains_text=banner&filter_by_asset_status_id=1&%24limit=50&%24offset=0", nil)
    if err != nil { log.Fatal(err) }
    request.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    response, err := (&http.Client{}).Do(request)
    if err != nil { log.Fatal(err) }
    defer response.Body.Close()
    body, err := io.ReadAll(response.Body)
    if err != nil { log.Fatal(err) }
    fmt.Printf("%d %s\n", response.StatusCode, body)
}
```

## Example response

Response 200 — OK 304 — Not Modified 400 — Bad Request 401 — Unauthorized 429 — Too Many Requests 500 — Internal Server Error

Example Successful request

```json
{
  "records_found": 1,
  "total_records": 1,
  "has_more": false,
  "list_type": "asset",
  "list_data": [
    {
      "workspace_id": 98765,
      "id": 12345,
      "asset_reservation_policy_id": 1,
      "exhibitday_url": "https://www.exhibitday.com/Workspace/Asset/98765?aid=12345",
      "internal_identifier": "",
      "asset_type_id": 1,
      "make_or_model": "",
      "asset_status_id": 1,
      "asset_status": "Active",
      "description": "",
      "name": "Display stand",
      "default_storage_location_id": 2345,
      "current_status": "Available / In Storage",
      "storage_location_name": "Main Warehouse",
      "returns_to_storage": "",
      "storage_location_address_display_name": "Boston, MA",
      "storage_area": "",
      "pull_notes": "",
      "status_message": null,
      "in_progress_reservation_count": 0,
      "quantity_available_in_storage": 1,
      "status_message_expires": null,
      "projected_future_balance": 1,
      "cost": {
        "amount": 0.00
      },
      "current_storage_footprint": 0.00,
      "dimensions_length": null,
      "projected_future_footprint": 0.00,
      "dimensions_width": null,
      "dimensions_unit": "in",
      "dimensions_height": null,
      "volume_unit": "cu ft",
      "dimensions_notes": "",
      "has_complete_dimensions": false,
      "dimensions_packaged_length": null,
      "dimensions_packaged_width": null,
      "dimensions_packaged_height": null,
      "dimensions_packaged_notes": "",
      "weight": null,
      "weight_notes": "",
      "weight_packaged": null,
      "weight_packaged_notes": "",
      "integration_metadata_field_1": null,
      "integration_metadata_field_2": null,
      "integration_metadata_field_3": null,
      "integration_metadata_field_4": null,
      "integration_metadata_field_5": null,
      "asset_created_timestamp": "2030-01-02T17:00:00Z",
      "weight_unit": "lb",
      "tags": [],
      "optional_accessories": [],
      "custom_fields": [],
      "images": [],
      "reservations": null
    }
  ]
}
```

Note: GET /v1/assets - HTTP 200. One page of Active Assets whose names contain banner. Use your own search text and keep the returned Asset IDs.

Note: There is no response body. Keep using your cached response.

```json
{
  "status_code": 400,
  "status": "Bad Request",
  "message": "HTTP method override is not supported.",
  "error_code": "invalid_request",
  "errors": [
    "Send the documented HTTP method directly. X-HTTP-Method-Override cannot change a request's HTTP method."
  ],
  "error_params": [
    "X-HTTP-Method-Override"
  ],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

```json
{
  "status_code": 401,
  "status": "Unauthorized",
  "message": "No API key was provided. Send your key in the Authorization header as 'Bearer YOUR_API_KEY'. Alternatively, you can use the api_key parameter.",
  "error_code": "missing_api_key",
  "errors": [
    "Copy the key from Workspace Settings > API & Integrations > API Access in ExhibitDay."
  ],
  "error_params": [
    "api_key"
  ],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

```json
{
  "status_code": 401,
  "status": "Unauthorized",
  "message": "The API key is not valid. Check that you copied the whole key from Workspace Settings > API & Integrations > API Access, then send it in the Authorization header as 'Bearer YOUR_API_KEY'. Alternatively, you can use the api_key parameter.",
  "error_code": "invalid_api_key",
  "errors": [
    "Check that you sent the whole key. If it was regenerated, use the current key from Workspace Settings > API & Integrations > API Access."
  ],
  "error_params": [
    "api_key"
  ],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

```json
{
  "status_code": 401,
  "status": "Unauthorized",
  "message": "Access to the ExhibitDay API is not enabled for your workspace. Please contact support@exhibitday.com to enable API Access. Once access is enabled, send your key in the Authorization header as 'Bearer YOUR_API_KEY'.",
  "error_code": "api_access_disabled",
  "errors": [
    "Nothing was read or changed."
  ],
  "error_params": [
    "api_key"
  ],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

```json
{
  "status_code": 429,
  "status": "Too Many Requests",
  "message": "Error 429 - Too Many Requests",
  "error_code": "rate_limited",
  "errors": [
    "Error 429 - Too Many Requests"
  ],
  "error_params": [],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

```json
{
  "status_code": 500,
  "status": "Unexpected Internal Error",
  "message": "An unexpected error occurred. Please try again later.",
  "error_code": "internal_error",
  "errors": [
    "An unexpected error occurred. Please try again later."
  ],
  "error_params": [],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

Note: Use the request_id from your own response when contacting support.

```json
{
  "status_code": 500,
  "status": "Unexpected Internal Error",
  "message": "An unexpected error occurred. Please try again later.",
  "error_code": "internal_error",
  "errors": [
    "Check whether your change was saved before trying again."
  ],
  "error_params": [],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

The curl example uses Bash. Node.js needs version 18 or later (save as .mjs). Python uses Requests. C# needs a .NET 8 console project (Program.cs). Java needs Java 11 or later (ExhibitDayExample.java). PHP needs PHP with cURL. Ruby and Go use their standard libraries.

## Things to keep in mind

- Send one custom-field search per request.
- Multi-line text fields are saved as formatted text (HTML). The search turns common codes, such as curly apostrophes, ampersands (&), non-breaking spaces and line breaks, into plain characters, so the words you type match. A word with formatting inside it, such as one bold letter, may still not match.
- An empty value means “nothing saved” only for the custom-field search. A blank name, tag or integration field filter is ignored.
- Integration field filters match the whole value. They ignore letter case and spaces before or after it, but accents count.
- Collateral has no default Storage Location, so the Storage Location filter returns Capital Assets only.
- With `hydrate_reservations=true`, each matching Asset lists all the reservations you can see, not only the ones that matched your date filters.

## Related guides

- [Check Asset Availability Before You Reserve](https://api.exhibitday.com/Help/V1?guide=check-asset-availability)
- [Reserve Assets (Equipment and Materials) for an Event](https://api.exhibitday.com/Help/V1?guide=reserve-change-cancel-assets)
- [Update Collateral Stock After a Delivery or Recount](https://api.exhibitday.com/Help/V1?guide=collateral-inventory-storage)
- [Search Events by Name, Custom Field or Tag](https://api.exhibitday.com/Help/V1?guide=search-events)
