> For the complete documentation index, see [llms.txt](https://support.pears.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.pears.io/plan/community-events/event-list-endpoint.md). # Event List Endpoint Access public community event data programmatically through the PEARS Event List API 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//events-api/ ``` Replace `` 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//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_at` * `created_at` * `modified_at` Without an `ordering` parameter, events are sorted by start date, earliest first. **Example:** ``` ?ordering=-start_at ``` ## Search Use the `q` parameter to search event titles and details. **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 | | `city` | City identifier used as the starting point for `max_range` | | `max_range` | Maximum distance in miles from the `city`; ignored without `city` | **Example:** ``` ?unit=1&has_fee=true&is_virtual=false&city=&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 or null | Cover image's unique identifier | | `cover_image_download_url` | String or null | URL for downloading the original cover image | | `cover_image_16x9_card_url` | String or null | 640×360 version of the cover image | | `cover_image_16x9_detail_url` | String or null | 960×540 version of the cover image | | `listing_thumbnail_upload` | Integer or null | Listing thumbnail's unique identifier | | `listing_thumbnail_download_url` | String or null | URL for downloading the original listing thumbnail | | `listing_thumbnail_square_list_url` | String or null | 500×500 version of the listing thumbnail | | `listing_image_square_url` | String or null | 500×500 listing image: the listing thumbnail, or the cover image cropped square if there is no thumbnail | | `start_at` | ISO 8601 DateTime | Event start, in the event's time zone | | `end_at` | ISO 8601 DateTime | Event end, in the event's time zone | | `site_name` | String | Event location name (empty if none) | | `is_published` | Boolean | Publication status | | `is_in_person` | Boolean | Whether in-person attendance is available | | `is_virtual` | Boolean | Whether virtual attendance is available | | `is_promotional` | Boolean | Whether the event is promotional only, with no registration | | `created_at` | ISO 8601 DateTime | Event creation timestamp | | `modified_at` | ISO 8601 DateTime | Last modification timestamp | | `confirmation_message` | String (HTML) or null | Registration confirmation text | | `has_fee` | Boolean | Whether the event charges fees | | `time_zone` | String | Event time zone name | | `short_time_zone` | String | Event time zone abbreviation | | `is_registration_full` | Boolean | Whether registration is full | | `is_registration_closed` | Boolean | Whether registration is closed | | `is_waitlist_available` | Boolean | Whether a waitlist is open for registration | | `display_name` | String | Formatted event title | The image URLs fall back to your organization's default cover image and listing thumbnail when the event has none. {% hint style="warning" %} **NOTE:** Only published, listed, non-internal events that have not yet ended 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, "cover_image_download_url": "https://pears.io/uploads/download/428743/", "listing_thumbnail_download_url": null, "cover_image_16x9_card_url": "https://pears.io/events/image-variant/428743/?redirect=1&size=640x360&permission_token=...", "cover_image_16x9_detail_url": "https://pears.io/events/image-variant/428743/?redirect=1&size=960x540&permission_token=...", "listing_thumbnail_upload": null, "listing_thumbnail_square_list_url": null, "listing_image_square_url": "https://pears.io/events/image-variant/428743/?redirect=1&size=500x500&permission_token=...&crop=center", "start_at": "2024-04-23T09:00:00-05:00", "end_at": "2024-04-23T16:00:00-05:00", "site_name": "4-H", "is_published": true, "is_in_person": true, "is_virtual": true, "is_promotional": false, "created_at": "2024-03-11T20:44:40.225542-05:00", "modified_at": "2024-04-03T08:59:16.416519-05:00", "confirmation_message": "

Thank you for registering...

", "has_fee": false, "time_zone": "US/Central", "short_time_zone": "CDT", "is_registration_full": false, "is_registration_closed": false, "is_waitlist_available": false, "display_name": "The Art And Science Of Agricultural Technology (Symposium)" } ] } ``` ## Support If you need help using this endpoint, contact PEARS support: * Email: * Phone: (785) 789-3199 * Hours: Monday–Friday, 8am–5pm Central time