Participations

A participation represents one user taking part in one event — for example, someone who applied to, registered for, or checked in to a hackathon. Each participation ties a user to an event and carries the person's status and contact details for that event.

You create and manage participations through an upsert endpoint (POST/PUT /v4/participations), and read or remove a single participation by its id. All requests are authenticated — see Authentication — and follow the shared conventions in Making requests.

Endpoints

Method	Path	What it does
POST	/v4/participations	Create or update a participation (upsert)
PUT	/v4/participations	Create or update a participation (upsert)
GET	/v4/participations/{id}	Get one participation
DELETE	/v4/participations/{id}	Delete a participation

POST and PUT /v4/participations behave identically — both perform the same upsert.

Upsert behavior

There is no separate "create" and "update" call. POST /v4/participations and PUT /v4/participations both upsert: they create a new participation, or update an existing one if a match is found.

A participation is identified by the user and event pair it belongs to. When you send a request:

• If no participation exists for that user and event, a new one is created.
• If one already exists, its fields are updated in place — you get back the same participation with a stable id rather than a duplicate.

You can also target a specific record by including its id in the request body.

Request-body fields

Field	Required	What it does
user	Required	The ID of the user taking part. Example: "usr_a1b2c3".
event	Required	The ID of the event they're participating in. Example: "evt_x9y8z7".
status	Optional	Where the person is in the event lifecycle. One of applied, rejected, accepted, registered, checked_in, canceled. Example: "registered".
first_name	Optional	The participant's first name. Example: "Ada".
last_name	Optional	The participant's last name. Example: "Lovelace".
email	Optional	The participant's email for this event. Example: "ada@example.com".
phone_number	Optional	The participant's phone number. Example: "+1-555-0100".
custom_fields	Optional	A free-form object of extra key/value data for the participation. Example: { "t_shirt_size": "M" }.
source	Optional	Where the participation came from. One of ohq, manual_import, csvifier, flatfile, avo_upload, csv_upload. Example: "csv_upload".
id	Optional	The ID of an existing participation to update. Omit it to let the upsert match on user and event.
created_at	Optional	An ISO 8601 datetime string. Normally set by the API; only send it when importing historical data.
updated_at	Optional	An ISO 8601 datetime string. Normally set by the API; only send it when importing historical data.

Fields

A participation returned by GET /v4/participations/{id} has these fields:

Field	Type	Notes
id	string	The participation's unique ID. Read-only.
user	string	The ID of the participating user. Settable on upsert.
event	string	The ID of the event. Settable on upsert.
status	string	One of applied, rejected, accepted, registered, checked_in, canceled. Settable.
first_name	string	Participant's first name. Settable.
last_name	string	Participant's last name. Settable.
email	string	Participant's email. Settable.
phone_number	string	Participant's phone number. Settable.
custom_fields	object	Extra key/value data. Settable.
source	string	One of ohq, manual_import, csvifier, flatfile, avo_upload, csv_upload. Settable.
created_at	integer	When the participation was created, as a Unix timestamp (seconds). Read-only.
updated_at	integer	When the participation was last updated, as a Unix timestamp (seconds). Read-only.

Note the timestamp difference between reads and writes: GET responses return created_at and updated_at as Unix timestamps (integers), while the upsert request body accepts them as ISO 8601 datetime strings.

Expanding related data

On GET /v4/participations/{id}, use expand[] to include related records inline instead of just their IDs. You can expand event and user:

GET /v4/participations/{id}?expand[]=event&expand[]=user

See Making requests for how expand works across the API.

Scopes

Requests authenticate with OAuth 2.0 or a bearer JWT, as described in Authentication. Request only the scopes your integration needs — see the full list of scopes.

Listed under parent resources

This page owns the core participation resource — upsert, get, and delete. To list participations, use the collection endpoints on a parent resource:

Path	Lists participations for
/v4/events/{event_id}/participations	an event
/v4/users/{user_id}/participations	a user
/v4/programs/{program_id}/participations	a program
/v4/series/{series_id}/participations	a series

These list endpoints support the shared pagination and filtering conventions in Making requests. See Events and Users for the event- and user-scoped lists.

Examples

Upsert a participation (create or update):

POST /v4/participations
Content-Type: application/json

{
  "user": "usr_a1b2c3",
  "event": "evt_x9y8z7",
  "status": "registered",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "source": "csv_upload"
}

Get one participation, expanding the user and event:

GET /v4/participations/{id}?expand[]=user&expand[]=event

Delete a participation:

DELETE /v4/participations/{id}

Related

• V4 API overview
• Making requests — pagination, filtering, expanding, and errors.
• Authentication
• Events
• Users