# Event List Endpoint

The PEARS Event List Endpoint provides programmatic access to an organization's published community events. Use it to display events on external websites, sync with other systems, or build custom integrations.

## Endpoint URL

```
https://pears.io/events/<org_slug>/events-api/
```

Replace `<org_slug>` with your organization's public identifier.

{% hint style="info" %}
**TIP:** Contact PEARS support if you don't know your organization's public slug.
{% endhint %}

## Pagination

Results are paginated, returning 20 items per page by default.

| Parameter   | Description                              |
| ----------- | ---------------------------------------- |
| `page`      | Page number to retrieve                  |
| `page_size` | Number of results per page (default: 20) |

**Example:**

```
https://pears.io/events/<org_slug>/events-api/?page=2&page_size=10
```

The paginated response includes the following metadata fields:

| Field              | Type           | Description                         |
| ------------------ | -------------- | ----------------------------------- |
| `next`             | String or null | URL of the next page of results     |
| `previous`         | String or null | URL of the previous page of results |
| `count`            | Integer        | Total number of matching results    |
| `num_pages`        | Integer        | Total pages available               |
| `page_size`        | Integer        | Results per page                    |
| `current_page_num` | Integer        | The current page number             |

## Ordering

Use the `ordering` parameter to sort results. Prefix a field name with a hyphen (`-`) to reverse the sort order.

Available fields:

* `title`
* `start_date`
* `created_at`
* `modified_at`

**Example:**

```
?ordering=-start_date
```

## Search

Use the `q` parameter to filter events by title.

**Example:**

```
?q=agriculture
```

## Filtering

Narrow results using one or more of the following filter parameters.

| Parameter    | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `unit`       | Unit identifier                                            |
| `has_fee`    | Boolean indicating whether the event has a fee             |
| `zip_code`   | Filter by location ZIP code                                |
| `is_virtual` | Boolean for virtual (`true`) or in-person (`false`) events |
| `max_range`  | Maximum distance range from the ZIP code                   |

**Example:**

```
?unit=1&has_fee=true&zip_code=66502&is_virtual=false&max_range=50
```

## Response Fields

Each event object in the `results` array includes the following fields:

| Field                      | Type                      | Description                               |
| -------------------------- | ------------------------- | ----------------------------------------- |
| `id`                       | Integer                   | Event's unique identifier                 |
| `title`                    | String                    | Event name                                |
| `summary`                  | String                    | Brief event description                   |
| `event_image_upload`       | Integer                   | Unique image identifier                   |
| `event_image_download_url` | String                    | URL for downloading the event image       |
| `start_date`               | ISO 8601 DateTime         | Event start timestamp                     |
| `end_date`                 | ISO 8601 DateTime or null | Event end timestamp                       |
| `site_display`             | String                    | Event location name                       |
| `is_published`             | Boolean                   | Publication status                        |
| `is_in_person`             | Boolean                   | Whether in-person attendance is available |
| `is_virtual`               | Boolean                   | Whether virtual attendance is available   |
| `created_at`               | ISO 8601 DateTime         | Event creation timestamp                  |
| `modified_at`              | ISO 8601 DateTime         | Last modification timestamp               |
| `confirmation_message`     | String (HTML)             | Registration confirmation text            |
| `payment_instructions`     | String (HTML) or null     | Fee payment details                       |
| `has_fee`                  | Boolean                   | Whether the event charges fees            |
| `time_zone`                | String                    | Event timezone designation                |
| `display_name`             | String                    | Formatted event title                     |

{% hint style="warning" %}
**NOTE:** Only published events are returned by this endpoint.
{% endhint %}

## Example Response

A successful request returns a JSON object with pagination metadata and a `results` array of event objects.

```json
{
  "default_ordering": "",
  "ordering": "",
  "next": null,
  "previous": null,
  "count": 3,
  "num_pages": 1,
  "page_size": 20,
  "current_page_num": 1,
  "results": [
    {
      "id": 1,
      "title": "The Art and Science of Agricultural Technology (Symposium)",
      "summary": "Agricultural Technology stands as a pillar in our quest for advancement and understanding.",
      "event_image_upload": 428743,
      "event_image_download_url": "http://localhost:8000/uploads/download/428743/",
      "start_date": "2024-04-23T00:00:00-05:00",
      "end_date": null,
      "site_display": "4-H",
      "is_published": true,
      "is_in_person": true,
      "is_virtual": true,
      "created_at": "2024-03-11T20:44:40.225542-05:00",
      "modified_at": "2024-04-03T08:59:16.416519-05:00",
      "confirmation_message": "<p>Thank you for registering...</p>",
      "payment_instructions": null,
      "has_fee": false,
      "time_zone": "US/Central",
      "display_name": "The Art And Science Of Agricultural Technology (Symposium)"
    }
  ]
}
```

## Support

If you need help using this endpoint, contact PEARS support:

* Email: <support@pears.io>
* Phone: (785) 789-3199
* Hours: Monday–Friday, 8am–5pm CST


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.pears.io/plan/community-events/event-list-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.