> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/intelligence/events.md).

# Events

Search conferences and industry events, and the people Sumble matched as their speakers. These endpoints return what the Events page in Sumble shows.

## Search events

Filter by the event itself (`period`, `locations`, `keywords`) and by its people (`person_ids`, `organization_ids`, `account_list_ids`, `job_functions`, `job_levels`, `account_status`, `crm`). An event matches when any of its people match the people filters. Send at least `{}` as the body. Every filter is optional: leaving one out, `null` and `[]` all mean no filter. Filters are combined with AND; values inside each filter array are combined with OR.

```bash
curl https://api.sumble.com/v9/events \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "period": "upcoming",
      "locations": ["US:California"],
      "account_list_ids": [4],
      "job_levels": ["VP", "Director"]
    },
    "order_by_column": "date"
  }'
```

`period` is `upcoming` (the default), `previous` or `all`. `locations` takes location codes such as `US`, `US:Texas` or `US:Texas:Austin`, or `VIRTUAL`; use [Location find](https://docs.sumble.com/api/lookups/locations.md) to turn place names into codes. `keywords` matches words in the event's name, location, topics or sponsors, or in a person's name, title or company, and supports quotes, `or` and `-` as in web search.

`account_status` takes `customer`, `prospect` or `not_in_crm`, describing the CRM account of each person's employer, or `yours` for an employer with a CRM account you own. `crm` takes `champion`, `new_lead` or `yours`, describing the person's own CRM record. Both need a linked CRM, and `crm` also needs CRM people matched to Sumble; without them a person's `crm` flags are `null`. Either filter returns a 400 when your account can't apply it.

`person_ids` keeps the events those people appeared at. With `"period": "all"` it finds every one, past and upcoming.

Your ICP ranks events and people; it doesn't filter them. Without an ICP, `has_icp` in the response is `false`, `relevance` order falls back to start date, soonest first for `upcoming` events and latest first for `previous` and `all`, and each person's `relevance` is `null`.

### Ordering and pagination

`order_by_column` is `relevance` (the default: events with the most people who fit your ICP first) or `date` (soonest start first). `order_by_direction` (`ASC` or `DESC`) reverses either one.

Results default to 20 events per page, with a maximum `limit` of 100. Use `offset` to skip results. `total` counts matching events across all pages.

### Response

Each event has an `id`, `name`, `starts_on`, `ends_on`, `location`, `official_url`, a `sumble_url` to its page in Sumble, and two counts. `people_count` is everyone Sumble matched to the event, before any filter. `matching_people_count` is the people your filter matches, and `people` holds up to three of them, best fit to your ICP first. Use [Get an event](#get-an-event) for the rest.

Each person has a `person_id`, `name`, the `job_title`, `company` and `role` the event lists for them, the `speaker_page_url` that lists them, a `sumble_url` to their Sumble profile, their current `organization`, their ICP `relevance` from 0 to 1, and `crm` flags (`is_champion`, `is_owned_by_you`, `is_new_lead`) when you have a linked CRM.

### Credit cost

1 credit per event returned. Searches with no results do not consume credits.

## Get an event

Get one event by `id` with every person Sumble matched to it, best fit to your ICP first. The people filters from [Search events](#search-events) narrow them the same way, except `person_ids`, which only search takes.

```bash
curl https://api.sumble.com/v9/events/1234 \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "job_functions": ["Engineering"],
      "job_levels": ["VP", "Director"]
    }
  }'
```

People default to 100 per page, with a maximum `limit` of 100. `total_people` counts matching people across all pages. An unknown `id` returns 404.

### Credit cost

1 credit per person returned. A page with no people does not consume credits.
