# Search Events by Name, Custom Field or Tag

> Find Events by name, custom field value or tag, then narrow the list by dates, Participation Status and more.

This is the Markdown copy of https://api.exhibitday.com/Help/V1?guide=search-events 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 Events by name, custom field value or tag, then narrow the list by dates, Participation Status and more.

Example use case

Your regional teams record each show's Sales Region in a custom field. You want every upcoming expo, the shows in EMEA, the shows nobody has given a region yet, and your Priority shows for 2027.

What you'll end up with

The Events that match your search, with the IDs you need for later requests.

Before you start

Have a workspace API key. To search a custom field, know the name of a text or dropdown field your workspace uses.

Good to know

An Event must match every filter you send. Names can change and two Events can share a name, so keep the Event `id`.

## At a glance

Time to try

About 10 minutes

Effect on your data

Read-only

Endpoints

3

The requests only read Events and your workspace's custom field and tag lists. They change nothing.

- [`GET /v1/events`](https://api.exhibitday.com/Help/V1?epf=1#get-v1-events)
- [`GET /v1/references/event_custom_fields`](https://api.exhibitday.com/Help/V1?epf=3#get-v1-references-event_custom_fields)
- [`GET /v1/references/event_tags`](https://api.exhibitday.com/Help/V1?epf=3#get-v1-references-event_tags)

## How it works

1. Search Events by part of their name.
2. Look up a custom field's `id`, then search by the value saved in that field, or find Events 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 Events.
- `%`, `_` 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 Event 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 Events with nothing saved in that field.

## Search your Events

The custom-field examples use a text field called Sales Region with the ID `67890`. Use your own field ID from Step 2.

## Step 1: Search by part of the Event name

Find upcoming Events with `expo` anywhere in the name. Upcoming means Events that end today or later, so Events in progress are included. The later steps add `$return_event_lites=true` to keep each result short.

```bash
curl -X GET "https://api.exhibitday.com/v1/events?filter_by_event_name_contains_text=expo&filter_by_event_start_date_category=upcoming&%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,
      "name": "Sample Event",
      "start_date": "2026-12-22",
      "end_date": "2026-12-24"
    }
  ]
}
```

**Check:** Compare the dates before you keep an `id`. `Expo`, `EXPO` and `Medical Expos` all match `expo`.

## Step 2: Find the field you want to search

List your Event custom fields. Pick the one to search by its `field_label`, the name you see on the Event page.

```bash
curl -X GET "https://api.exhibitday.com/v1/references/event_custom_fields" -H "Authorization: Bearer YOUR_API_KEY"
```

**Example response (shortened)**

```json
{
  "records_found": 1,
  "list_data": [
    {
      "id": 67890,
      "field_name": "custom_67890",
      "event_tab": "Event Information",
      "field_type": "Text (Single-line)",
      "field_label": "Sales Region",
      "options": null,
      "is_hidden": false,
      "is_filterable": true
    }
  ]
}
```

**Check:** Use a field whose `is_filterable` is true. Text and dropdown fields can be searched on any tab, 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 Events whose Sales Region is `EMEA`.

```bash
curl -X GET "https://api.exhibitday.com/v1/events?filter_by_custom_field_value_setting_id=67890&filter_by_custom_field_value_setting_value=EMEA&%24return_event_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 `EMEA`, `EMEA North` and `South EMEA`.

```bash
curl -X GET "https://api.exhibitday.com/v1/events?filter_by_custom_field_value_setting_id=67890&filter_by_custom_field_value_setting_value=emea&filter_by_custom_field_value_setting_match=contains&%24return_event_lites=true&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

**Check:** For a dropdown field, send one of its `options`. Event Lite results don't include custom field values. Leave out `$return_event_lites` and add `hydrate_custom_fields=true` to see them.

## Step 4: Find Events with no value in a field

Send the field `id` without a value to find Events where nothing is saved in that field yet. Sending an empty value does the same.

```bash
curl -X GET "https://api.exhibitday.com/v1/events?filter_by_custom_field_value_setting_id=67890&%24return_event_lites=true&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

**Check:** These are the Events to fill in. A dropdown field's default choice isn't a saved value, so an Event where nobody picked a choice appears here.

## Step 5: Search by tag

List the tags your workspace uses, then find Events that have one whole tag.

```bash
curl -X GET "https://api.exhibitday.com/v1/references/event_tags" -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
curl -X GET "https://api.exhibitday.com/v1/events?filter_by_event_tag=Priority&%24return_event_lites=true&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

**Check:** `prio` doesn't match `Priority`, so send the whole tag. To find Events 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 Events list's other filters. They work together with your searches. This request asks for the second page of Committed, In-Person Events that start in 2027.

```bash
curl -X GET "https://api.exhibitday.com/v1/events?filter_by_start_date_greater_than_or_equal_to=2027-01-01&filter_by_start_date_smaller_than_or_equal_to=2027-12-31&filter_by_event_participation_type_id=1&filter_by_event_format_id=1&%24return_event_lites=true&%24limit=50&%24offset=50" -H "Authorization: Bearer YOUR_API_KEY"
```

Other filters you can add:

| To find | Send |
| --- | --- |
| Upcoming Events, including Events in progress | `filter_by_event_start_date_category=upcoming` |
| Past Events, or Events that start in one year | `filter_by_event_start_date_category=past`, or a year such as `2027` |
| Events that start or end in a date range | `filter_by_start_date_greater_than_or_equal_to`, `filter_by_start_date_smaller_than_or_equal_to`, `filter_by_end_date_greater_than_or_equal_to` and `filter_by_end_date_smaller_than_or_equal_to`, as `YYYY-MM-DD` |
| A Participation Status: `1` Committed, `2` Considering, `3` Not Going, or one of your own | `filter_by_event_participation_type_id` (IDs from `GET /v1/references/event_participation_types`) |
| A format: `1` In-Person, `2` Virtual, `3` Hybrid | `filter_by_event_format_id` |
| A star rating, from `0` (no rating) to `3` | `filter_by_event_star_rating` |
| Your system's ID in an integration field | `filter_by_integration_metadata_field_1` (fields 1 to 5) |
| Events added or changed since a time | `filter_by_last_update_timestamp_greater_than_or_equal_to` |
| A different order | `$result_sort`: `create_timestamp_asc`, `create_timestamp_desc`, `last_update_timestamp_asc` or `last_update_timestamp_desc` |

**Check:** Use the date category or the four date filters, not both. When you send a category, the date filters are ignored. Upcoming, Past and years use your workspace's time zone.

**Check:** Start with `$offset=0`. While `has_more` is true, ask for the next page with the same filters and add 50 to `$offset`. `total_records` counts every matching Event.

## 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_event_name_contains_text` | Part of an Event name in your workspace. The example uses `expo`. |
| `$limit` and `$offset` | The example reads up to 50 matches starting at offset 0. |

**Note.** This example only reads data. It lists upcoming Events whose name contains `expo`.

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/events?filter_by_event_name_contains_text=expo&filter_by_event_start_date_category=upcoming&%24limit=50&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript
const response = await fetch("https://api.exhibitday.com/v1/events?" + new URLSearchParams({ "filter_by_event_name_contains_text": "expo", "filter_by_event_start_date_category": "upcoming", "$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/events",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"filter_by_event_name_contains_text": "expo", "filter_by_event_start_date_category": "upcoming", "$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/events?filter_by_event_name_contains_text=expo&filter_by_event_start_date_category=upcoming&%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/events?filter_by_event_name_contains_text=expo&filter_by_event_start_date_category=upcoming&%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/events?filter_by_event_name_contains_text=expo&filter_by_event_start_date_category=upcoming&%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/events?filter_by_event_name_contains_text=expo&filter_by_event_start_date_category=upcoming&%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/events?filter_by_event_name_contains_text=expo&filter_by_event_start_date_category=upcoming&%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 409 — Conflict 429 — Too Many Requests 500 — Internal Server Error

Example Successful request

```json
{
  "records_found": 1,
  "total_records": 1,
  "has_more": false,
  "list_type": "event",
  "list_data": [
    {
      "id": 12345,
      "exhibitday_url": "https://www.exhibitday.com/Workspace/Event/98765?eid=12345",
      "name": "Sample Event",
      "start_date": "2026-12-22",
      "end_date": "2026-12-24",
      "participation_type_id": 1,
      "participation_type": "Committed",
      "format_id": 1,
      "format": "In-Person",
      "star_rating": 0,
      "tags": [],
      "website_url": "",
      "venue_name": "",
      "venue_address": "",
      "venue_location_display_name": "",
      "venue_address_latitude": "",
      "venue_address_longitude": "",
      "booth_size": "",
      "booth_number": "",
      "booth_reservation_status_id": 1,
      "booth_reservation_status": "Need to Reserve",
      "booth_reserve_by_date": "",
      "booth_date_reserved": "",
      "budget_booth_reservation": 0.00,
      "budget_booth_services": 0.00,
      "budget_attendee_registrations": 0.00,
      "budget_travel": 0.00,
      "budget_giveaways": 0.00,
      "budget_shipments": 0.00,
      "budget_event_activities": 0.00,
      "budget_misc_expenses": 0.00,
      "budget_sponsorships": 0.00,
      "total_sum_event_budgets": 0.00,
      "booth_reservation_cost": {
        "amount": 125.50,
        "cost_center_breakdown": [
          {
            "cost_center_id": 34567,
            "cost_center": "Marketing",
            "charge": 75.50
          },
          {
            "cost_center_id": 34568,
            "cost_center": "Operations",
            "charge": 50.00
          }
        ]
      },
      "cost_booth_reservation": 125.50,
      "booth_reservation_payment_status_id": 0,
      "booth_reservation_payment_status": "",
      "booth_reservation_payment_due_date": null,
      "booth_reservation_next_payment_due_date": null,
      "booth_reservation_payment_notes": null,
      "booth_reservation_invoice_attachment": {
        "id": 182345,
        "filename": "booth-reservation-invoice.pdf",
        "attachment_created_timestamp": "2027-01-30T12:00:00Z"
      },
      "cost_booth_services": 0.00,
      "cost_attendee_registrations": 0.00,
      "cost_travel_reservations": 0.00,
      "cost_giveaways": 0.00,
      "cost_shipments": 0.00,
      "cost_event_activities": 0.00,
      "cost_misc_expenses": 0.00,
      "cost_sponsorships": 0.00,
      "total_sum_event_costs": 125.50,
      "event_notes": "",
      "booth_notes": "",
      "budget_notes": "",
      "roi_notes": "",
      "roi_num_leads": 0,
      "roi_num_impressions_booth": 0,
      "roi_num_impressions_sponsorships": 0,
      "roi_num_impressions_media": 0,
      "roi_num_meetings_existing_customers": 0,
      "roi_num_meetings_new_customers": 0,
      "roi_amount_actual_sales": 0.00,
      "roi_amount_potential_sales": 0.00,
      "roo_score": null,
      "event_created_timestamp": "2026-11-22T17:00:00Z",
      "event_last_update_timestamp": "2026-11-22T17:00:00Z",
      "event_created_by": {
        "id": "11111111-2222-4333-8444-555555555555",
        "first_name": "Jane",
        "last_name": "Smith",
        "display_name": "Jane Smith",
        "email": "jane@example.invalid",
        "type": "user",
        "workspace_role": "team_member",
        "is_active": true
      },
      "custom_fields": null,
      "task_sections": null,
      "tasks": null,
      "misc_expenses_credits": null,
      "integration_metadata_field_1": "",
      "integration_metadata_field_2": "",
      "integration_metadata_field_3": "",
      "integration_metadata_field_4": "",
      "integration_metadata_field_5": ""
    }
  ]
}
```

Note: GET /v1/events - HTTP 200. One page of upcoming Events whose names contain expo. Use your own search text and keep the returned Event 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": 409,
  "status": "Conflict",
  "message": "The invoice attachment or its owning record changed or has conflicting saved information. Retrieve the current record before retrying.",
  "error_code": "record_changed",
  "errors": [
    "The invoice attachment or its owning record changed or has conflicting saved information. Retrieve the current record before retrying."
  ],
  "error_params": [],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

```json
{
  "status_code": 409,
  "status": "Conflict",
  "message": "The Booth Reservation payment information changed or has an unsupported saved status. Retrieve the current Event before retrying.",
  "error_code": "record_changed",
  "errors": [
    "The Booth Reservation payment information changed or has an unsupported saved status. Retrieve the current Event before retrying."
  ],
  "error_params": [],
  "request_id": "0123456789abcdef0123456789abcdef"
}
```

```json
{
  "status_code": 409,
  "status": "Conflict",
  "message": "The Event objective score changed or could not be read consistently. Retrieve the Event before retrying.",
  "error_code": "record_changed",
  "errors": [
    "The Event objective score changed or could not be read consistently. Retrieve the Event before retrying."
  ],
  "error_params": [],
  "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. The older form, `filter_by_custom_event_field__custom_67890=EMEA`, still works and follows the same rules.
- You can search a hidden field. Event reads still leave out a hidden field's value.
- 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.
- Let your HTTP library encode query parameters. Encode `$` as `%24` in hand-written URLs.

## Related guides

- [Fill In Your Custom Event Fields from Another System](https://api.exhibitday.com/Help/V1?guide=custom-fields)
- [Search Tasks by Name, Details, Assignee and Due Date](https://api.exhibitday.com/Help/V1?guide=search-tasks)
- [Link ExhibitDay Events to Your CRM or ERP Records](https://api.exhibitday.com/Help/V1?guide=match-records)
- [Keep Another System Updated with Event and Task Changes](https://api.exhibitday.com/Help/V1?guide=sync-changes)
