> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.sessionboard.com/llms.txt > Use this file to discover all available pages before exploring further. # Search participants > Search every contact assigned to at least one session on the event in **any** participant role — the standard roles (speaker, chairperson, moderator) and any custom role configured for the event (Panelist, Coach, Author, …). This is the superset of `POST /v1/event/{eventId}/speakers`, which matches speakers only. Each contact is returned **once**, however many sessions or roles it holds, with a `roles` array listing every role it has on the event and the session ids where it holds each one. Every other field is the same `Contact` shape `POST /speakers` returns, in the same order, with `roles` appended last. `roles` always describes the contact's full set of roles on the event — it is not narrowed by the request filters, so a search filtered to the Moderator role still shows that a result is also a Speaker elsewhere on the program. **Filters.** Every Search Speakers filter is accepted and behaves the same: `createdAt`, `updatedAt`, `status` (the *session's* status), `trackIds`, `levelIds`, `formatIds`, `languageIds`, `tagIds`, plus `sort` and `expand`. Categorization filters are evaluated against the **top-level session**, so a participant on a subsession matches when the subsession's parent satisfies the filter. Each array filter needs at least one id — `[]` is a `400` naming the field; omit the property to apply no filter. Three filters are specific to this endpoint: - `roleIds` — return only participants holding **at least one** of the given roles, standard or custom. Get the ids from `GET /v1/event/{eventId}/participant-roles`. - `roleSlugs` — the same, by role slug (`speaker`, `chairperson`, `moderator`, or a custom role's slug). Use this to get every speaker without resolving ids per event, or on older events where roles have `roleId: null`. - `email` — exact, case-insensitive match on the contact's email. An unknown address returns an empty `results` array with `totalResults: 0`, not an error. For a single-record lookup that answers `404` instead, use `GET /v1/event/{eventId}/participants?email=`. **Roles on older events.** Roles are stored per event. An event that has never been opened in the Sessions editor may not have its standard roles created yet; its participants are still returned, but a standard role on such an event has `roleId: null` (with `roleName`, `slug` and `coreRole` filled in) and cannot be matched by `roleIds` until the roles exist — filter by `roleSlugs` instead. `GET .../participant-roles` returns an empty list for such an event. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/event/{eventId}/participants openapi: 3.1.0 info: title: Sessionboard Public API version: '1.0' description: >- REST API for managing sessions, speakers, contacts, sponsors, exhibitors, and event data on the Sessionboard platform. contact: name: Sessionboard Support email: support@sessionboard.com termsOfService: https://www.sessionboard.com/legal/terms-of-service servers: - url: https://public-api.sessionboard.com description: US Region - url: https://public-api-eu.sessionboard.com description: EU Region security: - ApiKey: [] - BearerToken: [] tags: - name: Events description: Manage events on the platform. - name: Sessions description: Search and retrieve sessions within an event. - name: Session Writes description: >- Create, update, delete, and restore sessions. Requires the `write:sessions` scope. - name: Contact Writes description: >- Create, update, delete, and restore contacts. Requires the `write:contacts` scope. - name: Exhibitor Writes description: >- Create, update, delete, and restore exhibitors. Requires the `write:exhibitors` scope. - name: Sponsor Writes description: >- Create, update, delete, and restore sponsors. Requires the `write:sponsors` scope. - name: Field Writes description: >- Create, update, and delete custom fields. Requires the `write:fields` scope. - name: Speakers description: Search and retrieve speakers within an event. - name: Participants description: | Search and retrieve every contact holding a session role on an event — speakers, chairpersons, moderators and custom roles — with the roles each one holds, and list the event's participant roles. - name: Contacts description: Search and retrieve contacts at the organization or event level. - name: Sponsors description: Search and retrieve sponsors within an event. - name: Exhibitors description: Search and retrieve exhibitors within an event. - name: Event Settings description: >- Retrieve event configuration such as fields, tags, tracks, rooms, formats, levels, languages, and session statuses. - name: GDPR description: Manage GDPR data access and erasure requests. - name: Insights description: >- Query event data using SbQL, generate queries with AI, and manage dashboards. - name: Metadata Writes description: >- Create, update, and delete session metadata (rooms, tracks, tags, formats, levels, languages, statuses). Requires the `write:metadata` scope. - name: Agenda Planning description: >- Manage agenda drafts, draft sessions, scheduling rules, and evaluation personas. Requires the `write:events` scope. - name: Dashboards & Widgets description: >- Create, read, update, and delete dashboards and widgets at the event or organization level. Requires `write:events` scope for writes. - name: Reports & Queries description: >- Create, read, update, delete, and run saved SbQL queries/reports at the event or organization level. Requires `write:events` scope for writes. - name: Transcriptions description: >- Transcript text on sessions — fragments, summaries, insights, and translations. Requires `read:transcriptions` / `write:transcriptions` scopes. - name: Session Recordings description: >- Session audio files for recording archives (live capture or imported audio). Requires `read:transcriptions` / `write:transcriptions` scopes. - name: Media description: >- Upload video or audio files for automatic transcription. Requires `read:media` / `write:media` scopes. - name: Session Files description: > Documents attached to sessions (PDFs, PowerPoint, Word, images, and similar). Simple upload: `POST .../files/upload` (multipart, max 50 MB). Direct-to-storage: create → PUT → complete (max 500 MB). Requires `read:sessions` / `write:sessions` scopes. See the [Uploading session files](/guides/uploading-session-files) guide. - name: OAuth description: >- OAuth 2.1 endpoints for AI client authorization (Claude, ChatGPT). Mounted at `/oauth/` (not `/v1/`). paths: /v1/event/{eventId}/participants: post: tags: - Participants summary: Search participants description: | Search every contact assigned to at least one session on the event in **any** participant role — the standard roles (speaker, chairperson, moderator) and any custom role configured for the event (Panelist, Coach, Author, …). This is the superset of `POST /v1/event/{eventId}/speakers`, which matches speakers only. Each contact is returned **once**, however many sessions or roles it holds, with a `roles` array listing every role it has on the event and the session ids where it holds each one. Every other field is the same `Contact` shape `POST /speakers` returns, in the same order, with `roles` appended last. `roles` always describes the contact's full set of roles on the event — it is not narrowed by the request filters, so a search filtered to the Moderator role still shows that a result is also a Speaker elsewhere on the program. **Filters.** Every Search Speakers filter is accepted and behaves the same: `createdAt`, `updatedAt`, `status` (the *session's* status), `trackIds`, `levelIds`, `formatIds`, `languageIds`, `tagIds`, plus `sort` and `expand`. Categorization filters are evaluated against the **top-level session**, so a participant on a subsession matches when the subsession's parent satisfies the filter. Each array filter needs at least one id — `[]` is a `400` naming the field; omit the property to apply no filter. Three filters are specific to this endpoint: - `roleIds` — return only participants holding **at least one** of the given roles, standard or custom. Get the ids from `GET /v1/event/{eventId}/participant-roles`. - `roleSlugs` — the same, by role slug (`speaker`, `chairperson`, `moderator`, or a custom role's slug). Use this to get every speaker without resolving ids per event, or on older events where roles have `roleId: null`. - `email` — exact, case-insensitive match on the contact's email. An unknown address returns an empty `results` array with `totalResults: 0`, not an error. For a single-record lookup that answers `404` instead, use `GET /v1/event/{eventId}/participants?email=`. **Roles on older events.** Roles are stored per event. An event that has never been opened in the Sessions editor may not have its standard roles created yet; its participants are still returned, but a standard role on such an event has `roleId: null` (with `roleName`, `slug` and `coreRole` filled in) and cannot be matched by `roleIds` until the roles exist — filter by `roleSlugs` instead. `GET .../participant-roles` returns an empty list for such an event. operationId: search-participants parameters: - name: eventId in: path required: true schema: type: integer description: The event ID. - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ParticipantSearchBody' examples: byRole: summary: Everyone holding the Moderator or a custom role value: filters: roleIds: - 4efeb845-050f-4002-9496-cb586cdf10f2 - 52d60237-19db-4bda-a116-8b9fcb6750e9 status: accepted bySlug: summary: Every speaker, by role slug value: filters: roleSlugs: - speaker byEmail: summary: Match one contact by email value: filters: email: jane.smith@university.edu responses: '200': description: OK content: application/json: schema: type: object properties: results: type: array items: $ref: '#/components/schemas/Participant' pagination: $ref: '#/components/schemas/Pagination' '400': description: >- Validation error — an empty filter array, a non-UUID in `roleIds`, or an out-of-range `page` / `pageSize`. '401': description: Unauthorized '404': description: Event not found components: parameters: Page: name: page in: query required: false schema: type: integer minimum: 1 maximum: 999 default: 1 description: Page number for pagination. PageSize: name: pageSize in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 description: | Number of results per page. The event-settings list endpoints (tags, tracks, levels, formats, rooms, languages, statuses) also accept the older spelling `page_size`, and used to accept only that — a request sending `pageSize` silently got the default 25. Both now work, `pageSize` wins when both are sent, and on these endpoints a value outside 1–100 is clamped rather than rejected. Everywhere else `pageSize` is the only spelling. schemas: ParticipantSearchBody: type: object description: > Search request body for participants. Every `SpeakerSearchBody` filter is accepted with the same semantics (categorization filters match the participant's **top-level** session), plus `roleIds`, `roleSlugs` and `email`. properties: filters: type: object properties: createdAt: $ref: '#/components/schemas/DateRangeFilter' updatedAt: $ref: '#/components/schemas/DateRangeFilter' status: type: string enum: - accepted - accept_queue - pending - decline_queue - declined description: Match participants on sessions with this session status. trackIds: type: array minItems: 1 items: type: string format: uuid description: >- Send at least one ID — an empty array is rejected with a 400; to apply no track filter, omit the property. levelIds: type: array minItems: 1 items: type: string format: uuid formatIds: type: array minItems: 1 items: type: string format: uuid languageIds: type: array minItems: 1 items: type: string format: uuid tagIds: type: array minItems: 1 items: type: string format: uuid roleIds: type: array minItems: 1 items: type: string format: uuid description: | Return participants holding at least one of these roles (standard or custom). Ids come from `GET /v1/event/{eventId}/participant-roles`. An empty array is a 400; omit the property to match every role. roleSlugs: type: array minItems: 1 items: type: string minLength: 1 maxLength: 100 description: | Return participants holding at least one role with these slugs — the standard `speaker`, `chairperson`, `moderator`, or a custom role's `slug` from `GET .../participant-roles`. Works on events whose roles have `roleId: null`. Case-insensitive. Combines with `roleIds` as AND. An empty array is a 400. email: type: string minLength: 1 maxLength: 320 description: | Exact, case-insensitive match on the contact's email. An unknown address returns an empty result set, not an error. sort: $ref: '#/components/schemas/SortOptions' expand: type: array items: type: string enum: - translated_fields Participant: allOf: - $ref: '#/components/schemas/Contact' - type: object description: | A contact holding at least one session role on the event. Every `Contact` field is present with the same values `POST /speakers` returns; `roles` is appended after them. required: - roles properties: roles: type: array description: | Every role the contact holds on the event and the sessions it holds each one on. Always the contact's complete set — not narrowed by the request filters. Ordered by the role's configured sort order. items: $ref: '#/components/schemas/ParticipantRoleAssignment' examples: - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 friendly_id: SPK-42 full_name: Dr. Jane Smith first_name: Jane last_name: Smith email: jane.smith@university.edu created_at: '2023-11-01T10:00:00Z' updated_at: '2024-02-15T16:30:00Z' company_name: State University title: Professor of Computer Science custom_fields: [] roles: - roleId: 84bd12e5-d5ec-4c64-a604-4051e06c8dc2 roleName: Speaker slug: speaker coreRole: speaker isCustom: false sessionIds: - 04efb360-2b15-44db-b639-4035fae2772c - roleId: 4efeb845-050f-4002-9496-cb586cdf10f2 roleName: Moderator slug: moderator coreRole: moderator isCustom: false sessionIds: - 26e465fc-1fb1-4c04-af52-f4d6314dfca4 - roleId: 52d60237-19db-4bda-a116-8b9fcb6750e9 roleName: Panelist slug: panelist coreRole: speaker isCustom: true sessionIds: - 140b8e82-41ca-444e-82ab-f7dd1011e95b - 2c198cce-adff-4fb2-81e1-319b601d564b Pagination: type: object description: >- Pagination metadata returned with POST search responses. The event-settings GET lists return the same numbers under snake_case keys — see `ListPagination`. properties: currentPage: type: integer examples: - 1 pageSize: type: integer examples: - 25 totalPages: type: integer examples: - 4 totalResults: type: integer examples: - 97 DateRangeFilter: type: object description: Filter by a date range using before and/or after bounds. properties: before: type: string format: date-time description: Return records before this date-time. after: type: string format: date-time description: Return records after this date-time. SortOptions: type: object description: | Nested sort keys matching the search POST body (`createdAt.sort`, not a flat `order` enum). Each key is optional. properties: createdAt: $ref: '#/components/schemas/NestedSortField' updatedAt: $ref: '#/components/schemas/NestedSortField' Contact: type: object description: >- A contact (speaker, attendee, or organizational contact) in Sessionboard. properties: id: type: string friendly_id: type: string full_name: type: string first_name: type: string last_name: type: string email: type: string created_at: type: string updated_at: type: string photo_url: type: string company_name: type: string title: type: string about: type: string phone_home: type: string phone_mobile: type: string address_line_1: type: string address_line_2: type: string address_city: type: string address_state: type: string address_postal_code: type: string address_country: type: string website_url: type: string linkedin_url: type: string twitter_url: type: string facebook_url: type: string honorific: type: string salutation: type: string pronouns: type: string gender: type: string past_companies: type: string educational_affiliation: type: string highest_level_of_education: type: string ethnicity: type: string languages: type: string speaker_score: type: string organization_contact: type: string speaker_fee: type: string availability: type: string preferred_session_format: type: string annual_revenue: type: string headcount: type: string years_in_operation: type: string organization_structure: type: string industry: type: string global_region: type: string audience_type: type: string target_age_range: type: string topic_expertise: type: string brand: type: string translated_fields: type: array items: $ref: '#/components/schemas/TranslatedField' custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldValue' admin_url: type: string format: uri nullable: true description: Deep link to this entity in the Sessionboard admin UI. examples: - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 friendly_id: SPK-42 full_name: Dr. Jane Smith first_name: Jane last_name: Smith email: jane.smith@university.edu created_at: '2023-11-01T10:00:00Z' updated_at: '2024-02-15T16:30:00Z' photo_url: https://cdn.sessionboard.com/photos/jane-smith.jpg company_name: State University title: Professor of Computer Science about: Dr. Smith is a leading researcher in distributed systems. address_city: Austin address_state: TX address_country: US honorific: Dr. pronouns: she/her topic_expertise: Distributed Systems, Cloud Computing custom_fields: [] translated_fields: [] ParticipantRoleAssignment: type: object description: | One role a participant holds on the event, with the sessions it holds it on. Returned inside `Participant.roles`. required: - roleId - roleName - slug - coreRole - isCustom - sessionIds properties: roleId: type: - string - 'null' format: uuid description: | The role's id — the value to pass in the `roleIds` filter and the `id` returned by `GET /v1/event/{eventId}/participant-roles`. `null` only for a standard role on an event whose roles have not been created yet (see the endpoint description). roleName: type: string description: Display name of the role (singular), e.g. `Speaker`, `Panelist`. slug: type: string description: Stable programmatic identifier for the role within the event. coreRole: type: string enum: - speaker - chairperson - moderator description: The standard category the role maps to. Not a display label. isCustom: type: boolean description: >- `true` for a role the organizer added; `false` for Speaker, Chairperson and Moderator. sessionIds: type: array items: type: string format: uuid description: >- Ids of the sessions (including subsessions) on which the contact holds this role. NestedSortField: type: object description: | One sort key. `sort` is the direction; `order` is the priority when multiple keys are set (lower numbers apply first). properties: sort: type: string enum: - asc - desc order: type: integer TranslatedField: type: object description: A translated version of a field value. properties: id: type: string name: type: string type: type: string parent_field_id: type: string parent_field_source: type: string parent_field_name: type: string parent_field_internal_name: type: string translated_language: type: string value: type: string CustomFieldValue: type: object description: A custom field value attached to a record. properties: id: type: string name: type: string value: type: - string - boolean - 'null' description: | The formatted field value, or `null` when the field is empty. Numeric field types (`number`, `currency`, `percent`, `quantity`, `formula`) serialize a stored zero as its formatted value (for example `"0"`) — `null` means the field has no value, not that the value is zero. `checkbox` fields serialize as the strings `"Yes"` (checked) and `"No"` (explicitly unchecked); a checkbox that was never set is `null`. Writes take boolean `true` / `false`. `datetime` fields serialize as ISO 8601. On event custom fields (`GET /v1/events?expand=custom_fields`) the value is event-local time with the event's UTC offset (for example `2026-08-15T09:00:00-03:00`), falling back to the raw UTC instant (`2026-08-15T12:00:00.000Z`) when the event has no valid timezone. On session, speaker, sponsor, and exhibitor custom fields the value is the raw UTC instant. Date-only fields are unaffected. type: type: string internal_name: type: string created_at: type: string securitySchemes: ApiKey: type: apiKey in: header name: x-access-token description: >- Organization API token. Generate from Organization Settings → API Tokens. BearerToken: type: http scheme: bearer description: >- OAuth 2.1 access token. Obtained via the OAuth PKCE flow at `/oauth/token`. ````