> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roostedhr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Events
> Searches events using a combination of filters. Returns paginated results.
Searches events using a combination of filters. The response is paginated — use `items_per_page` and `page` query parameters.
`start_date` is the only required filter. All other filters are optional and combine with AND logic — only events matching every provided filter are returned.
Use the boolean filters (`unfilled`, `unpublished_shifts`, `pending_invites`) to surface events needing attention.
## OpenAPI
````yaml api-reference/v01.12.00/openapi-v01.12.00.json POST /events/search
openapi: 3.0.0
info:
title: Roosted
version: 0.1.12
contact:
name: Support
url: https://support.roostedhr.com/support/home
email: support@roostedhr.com
description: |-
Enterprise API
Sandbox keys and Production keys are requested from support
servers:
- url: https://api.roostedhr.com/api/1_12
- url: https://sandbox.roostedhr.com/api/1_12
security:
- X-API-KEY: []
tags:
- name: Announcements
- name: Areas
- name: Clients
- name: Company
- name: Configuration
- name: Events
- name: Locations
- name: Payroll Groups
- name: Rate Cards
- name: Shifts
- name: Skillsets
- name: Time Tracking
- name: Wage Rules
- name: Workers
paths:
/events/search:
post:
tags:
- Events
summary: Search Events
description: >-
Searches events using a combination of filters. Returns paginated
results.
operationId: post-events-search
parameters:
- schema:
type: number
in: query
name: items_per_page
description: Count of items per page
- schema:
type: number
in: query
name: page
description: Page
requestBody:
content:
application/json:
schema:
type: object
properties:
start_date:
type: string
format: date
example: '2001-01-01'
end_date:
type: string
format: date
example: '2001-01-01'
event_name:
type: string
description: Search text for event name
location_name:
type: string
description: Search text for location name of the event
tags:
type: array
description: Array of tag IDs
items:
type: string
areas:
type: array
description: Array of area IDs
items:
type: string
workers:
type: array
description: Array of worker IDs
items:
type: string
clients:
type: array
description: Array of client IDs
items:
type: string
skillsets:
type: array
description: Array of skillset IDs
items:
type: string
unfilled:
type: boolean
default: false
description: Fetched only events with unfilled shifts
unpublished_shifts:
type: boolean
default: false
description: Fetched only events with unpublished shifts
pending_invites:
type: boolean
default: false
description: Fetched only events with pending invites
required:
- start_date
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/Event'
total_count:
type: number
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: Machine-readable error code.
error:
type: string
description: Human-readable error message.
examples:
Invalid page parameter:
value:
code: EVT-1700
error: Invalid page parameter
Invalid per_page parameter:
value:
code: EVT-1800
error: Invalid per_page parameter
Start date is required:
value:
code: EVT-1900
error: Start date is required
Invalid date format:
value:
code: EVT-500
error: Invalid date format
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: Machine-readable error code.
error:
type: string
description: Human-readable error message.
examples:
Invalid API key:
value:
code: ATH-100
error: Invalid or missing API key
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: Machine-readable error code.
error:
type: string
description: Human-readable error message.
examples:
Insufficient permissions:
value:
code: EVT-800
error: Insufficient permissions to manage events
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: Machine-readable error code.
error:
type: string
description: Human-readable error message.
examples:
Event not found:
value:
code: EVT-700
error: Event not found
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: Machine-readable error code.
error:
type: string
description: Human-readable error message.
examples:
Unexpected error:
value:
code: EVT-1000
error: An unexpected error occurred
components:
schemas:
Event:
title: Event
type: object
properties:
id:
type: integer
name:
type: string
date:
type: string
format: date
event_id:
type: string
client_id:
type: string
created:
type: string
format: date
location:
$ref: '#/components/schemas/Location'
admin_origin:
$ref: '#/components/schemas/EventManager'
reviewer:
$ref: '#/components/schemas/EventManager'
time_tracking_manager:
$ref: '#/components/schemas/EventManager'
custom_fields:
type: array
items:
$ref: '#/components/schemas/CustomField'
areas:
type: array
nullable: true
description: Areas/zones assigned to the event. Null if none.
items:
type: object
properties:
id:
type: string
name:
type: string
Location:
title: Location
type: object
properties:
id:
type: string
description: Location identifier
location:
type: string
description: Location name
addy_street_number:
type: string
description: Street address
addy_city:
type: string
description: City
addy_zip:
type: string
description: ZIP/postal code
location_comments:
type: string
nullable: true
description: Additional comments
default:
type: integer
nullable: true
minimum: 0
maximum: 1
description: Whether this is the default location (0 or 1)
saved:
type: integer
nullable: true
minimum: 0
maximum: 1
description: Whether the location is saved (0 or 1)
color:
type: string
nullable: true
description: Hex color code
example: '#DC136C'
timezone:
type: object
description: Location timezone
properties:
id:
type: integer
nullable: true
description: Timezone identifier
name:
type: string
nullable: true
description: Timezone name
offset:
type: string
nullable: true
description: UTC offset
companies_payroll_rulesets_id:
type: string
nullable: true
description: Associated payroll ruleset ID
payroll_rule_display:
type: string
nullable: true
description: Payroll rule display name
latitude:
type: string
nullable: true
description: GPS latitude coordinate
longitude:
type: string
nullable: true
description: GPS longitude coordinate
default_clients_id:
type: string
nullable: true
description: Default client hashed ID
default_areas:
type: array
description: Default area IDs
items:
type: string
EventManager:
title: EventManager
type: object
properties:
personnel_id:
type: string
name:
type: string
CustomField:
title: CustomField
type: object
properties:
id:
type: string
name:
type: string
value:
type: string
options:
type: array
description: Available options for this custom field (e.g., dropdown choices).
items:
type: object
properties:
title:
type: string
value:
type: string
securitySchemes:
X-API-KEY:
name: X-API-KEY
type: apiKey
in: header
````