Events

An event is a hackathon, workshop, conference, meetup, or other happening in the MLH ecosystem. Events are the hub that most other data hangs off of: an event has staff, sponsorships, participations, project submissions, and an application that created it.

This page covers the event resource and its sub-resources:

Events — the events themselves.
Event Applications — an organizer's request to run an event.
Event Staffs — people working an event (organizers, observers, coaches).
Event Sponsorships — a company's sponsorship of a specific event.
Event Participations — who registered for or attended an event.
Event Challenges — the join between an event and a challenge.
Event Submissions — projects submitted to an event.

All of these follow the shared conventions for pagination, filtering, expand[], and error responses described in Making requests, and all requests are authenticated as described in Authentication. Event data is covered by the mlh:read:event and mlh:write:event scopes (plus the broader mlh and organizer scopes) — request only what you need.

Throughout, created_at and updated_at are read-only Unix timestamps (seconds since the epoch) in responses. When you send them on a create or update they are ISO 8601 datetime strings, but you normally leave them out and let the API set them. id is always read-only.

Events

The core resource. List, read, create, and update events.

Endpoints

Method	Path	What it does
`GET`	`/v4/events`	List events (paginated, filterable)
`GET`	`/v4/events/{id}`	Get one event
`POST`	`/v4/events`	Create an event
`PATCH` / `PUT`	`/v4/events/{id}`	Update an event
`GET`	`/v4/events/identify`	Look up an event by identifier

Fields

name — the event's display name, e.g. "HackNYU 2026". Set this on create.
slug — the URL-friendly identifier, e.g. "hacknyu-2026".
status — one of draft, pending, in_progress, ended, canceled.
private — boolean; true hides the event from public listings.
event_format — one of hackathon, hackday, presentation, workshop, conference, meetup, evergreen, campaigns, hackweek.
starts_at / ends_at — when the event runs. Send as ISO 8601 strings on create/update (e.g. "2026-03-14T09:00:00Z"); they are returned as Unix timestamps.
time_zone — the event's time zone, e.g. "America/New_York".
website_url, registration_url, chat_url, submission_url — public links for the event.
logo_url, background_url — image URLs used on the event page.
program — the program this event belongs to.
series / series_id — the series this event is part of.
parent / children — parent event and child events, for nested events.
prize_categories — the prize categories offered.
custom_fields — a free-form object for event-specific data.
address — the event's location.
organizer_emails — emails of the event's organizers.
event_staff_emails — emails of staff to associate with the event.
lead_organizer / organizers — the lead organizer and full organizer list.
sponsors / sponsorships — associated sponsor companies and sponsorships.
event_application — the application that produced this event.
promo_codes — promo codes tied to the event.
season_identifier — the season the event belongs to.

Read-only response fields also include the counters registrations_count, check_ins_count, and project_submissions_count, plus id, created_at, and updated_at.

You can expand[] these associations: prize_categories, series, sponsors, organizers, lead_organizer, sponsorships, and event_application. See Expanding related data.

Filtering

List supports filtering on id, name, slug, website_url, starts_at, ends_at, created_at, updated_at, private, event_format, status, program, series, parent, and event_type, using the operators from Filtering. For example:

GET /v4/events?status[eq]=in_progress&event_format[in]=hackathon,hackday

`GET /v4/events/identify`

Looks up a single event by an identifier (required query param). Pass auto_create=true to create the event if none is found. Use this when you have an external reference and want to resolve or provision the event in one call, rather than searching the list.

GET /v4/events/identify?identifier=hacknyu-2026

Example

Create an event:

POST /v4/events

{
  "name": "HackNYU 2026",
  "slug": "hacknyu-2026",
  "event_format": "hackathon",
  "status": "pending",
  "starts_at": "2026-03-14T09:00:00Z",
  "ends_at": "2026-03-15T18:00:00Z",
  "time_zone": "America/New_York"
}

Event Applications

An event application is an organizer's request to run an event; approving one produces an event. Applications carry the responses collected in the application flow plus CRM tracking fields.

Endpoints

Method	Path	What it does
`GET`	`/v4/event_applications`	List event applications
`GET`	`/v4/event_applications/{id}`	Get one event application
`POST`	`/v4/event_applications`	Create an event application
`PATCH` / `PUT`	`/v4/event_applications/{id}`	Update an event application
`GET`	`/v4/event_applications/identify`	Look up an application by identifier

Note this resource is not nested under an event — it lives at the top level (/v4/event_applications), unlike staffs, sponsorships, and participations.

Fields

name — the application's name, e.g. "HackNYU 2026 Application".
status — one of draft, submitted, approved, rejected, withdrawn.
rejection_reason — set when status is rejected.
withdraw_reason — set when status is withdrawn.
response — an object holding the submitted application answers.
metadata — a free-form object for extra data.
series_id — the series the application belongs to.
user — the user who submitted the application.
event — the event this application is (or becomes) associated with.
application_submitters / application_submitter_emails — the people submitting the application, by record or by email.
crm_id, crm_type (zoho or ohq), crm_stage_name, crm_owner — CRM tracking fields.
manage_url, ohq_application_url — links to manage the application.
logo_url, background_url — image URLs.

Read-only response fields include id, created_at, and updated_at.

Expanding and filtering

expand[] supports event, crm_owner, and application_submitters. List filtering is available on id, name, status, created_at, updated_at, submitted_at, series, event, user_id, and email. For example:

GET /v4/event_applications?status[in]=submitted,approved&email[eq]=organizer@example.com

`GET /v4/event_applications/identify`

Resolves a single application from an identifier (required), with optional auto_create=true. Use it to find an existing application by an external reference or provision one on the fly.

Example

POST /v4/event_applications

{
  "name": "HackNYU 2026 Application",
  "status": "draft",
  "application_submitter_emails": ["organizer@example.com"]
}

Event Staffs

An event staff record ties a user to an event with a role. This resource is nested under the event — every path includes {event_id}.

Endpoints

Method	Path	What it does
`GET`	`/v4/events/{event_id}/staffs`	List staff for an event
`GET`	`/v4/events/{event_id}/staffs/{id}`	Get one staff record
`POST`	`/v4/events/{event_id}/staffs`	Add a staff member to the event
`PATCH` / `PUT`	`/v4/events/{event_id}/staffs/{id}`	Update a staff record
`DELETE`	`/v4/events/{event_id}/staffs/{id}`	Remove a staff member

Fields

role — one of event_staff, observer, coach_on_call. Defines what this person does at the event.
lead — boolean; true marks this person as a lead.
user — the user who is on staff. Required to identify the person.
event — the event; normally supplied by the {event_id} in the path.
metadata — a free-form object for extra data.

Read-only response fields include id, created_at, and updated_at.

Expanding and filtering

expand[] supports event and user. List filtering is available on event and user.

Example

Add an observer to an event:

POST /v4/events/{event_id}/staffs

{
  "role": "observer",
  "lead": false,
  "user": "usr_123"
}

Event Sponsorships

An event sponsorship is a company's sponsorship of a specific event — including the call-to-action shown on the event page. Standard operations are nested under the event ({event_id}); there is also a top-level import endpoint.

Endpoints

Method	Path	What it does
`GET`	`/v4/events/{event_id}/sponsorships`	List sponsorships for an event
`GET`	`/v4/events/{event_id}/sponsorships/{id}`	Get one sponsorship
`POST`	`/v4/events/{event_id}/sponsorships`	Create a sponsorship on the event
`PATCH` / `PUT`	`/v4/events/{event_id}/sponsorships/{id}`	Update a sponsorship
`DELETE`	`/v4/events/{event_id}/sponsorships/{id}`	Remove a sponsorship
`POST`	`/v4/events/sponsorships`	Create sponsorships from OHQ (bulk import)

Fields

title — the sponsorship's display title, e.g. "Gold Sponsor".
name — the sponsor's name.
slug — a URL-friendly identifier.
domain_name — the sponsor's domain, e.g. "example.com".
cta_text — the call-to-action label shown on the event page, e.g. "We're hiring".
cta_url — the URL that call-to-action links to.
company_id — the company behind the sponsorship.
type — the sponsorship type.
event — the event; normally supplied by the {event_id} in the path.

Read-only response fields include id, created_at, and updated_at.

Expanding and filtering

expand[] supports event. List filtering is available on cta_text, title, created_at, updated_at, event, company, and sponsorship_type.

`POST /v4/events/sponsorships` (create from OHQ)

This top-level endpoint (note: not nested under an event) bulk-creates event sponsorships from OHQ data. Use it to import sponsorships pulled from OHQ rather than creating each one by hand under /v4/events/{event_id}/sponsorships.

Example

Create a sponsorship on an event:

POST /v4/events/{event_id}/sponsorships

{
  "title": "Gold Sponsor",
  "name": "Example Corp",
  "cta_text": "We're hiring",
  "cta_url": "https://example.com/careers",
  "company_id": "cmp_123"
}

Event Participations

A participation records a person's relationship to an event — that they applied, registered, checked in, and so on. Under events, participations are read-only: you can list them for an event, but you create and update them through the top-level Participations endpoints.

Endpoints

Method	Path	What it does
`GET`	`/v4/events/{event_id}/participations`	List participations for an event

Fields (read-only here)

status — one of applied, rejected, accepted, registered, checked_in, canceled.
first_name, last_name, email, phone_number — the participant's contact details.
source — where the record came from: ohq, manual_import, csvifier, flatfile, avo_upload, or csv_upload.
custom_fields — a free-form object.
user — the participating user.
event — the event; matches the {event_id} in the path.

Read-only response fields include id, created_at, and updated_at.

expand[] supports event and user.

To create, update, or delete a participation, use the top-level participation endpoints described in Participations.

Example

GET /v4/events/{event_id}/participations?expand[]=user

Event Challenges

An event challenge is the join record that links an event to a challenge. This resource is nested under the event ({event_id}) and exposes only update and delete — you attach challenges to events elsewhere and manage the link here.

Endpoints

Method	Path	What it does
`PATCH` / `PUT`	`/v4/events/{event_id}/challenges/{id}`	Update an event–challenge link
`DELETE`	`/v4/events/{event_id}/challenges/{id}`	Remove a challenge from the event

Fields

event_id / event — the event side of the link (the path already carries {event_id}).
challenge_id / challenge — the challenge side of the link.

Read-only response fields include id, created_at, and updated_at.

Example

Remove a challenge from an event:

DELETE /v4/events/{event_id}/challenges/{id}

Event Submissions

An event submission records a project submitted to an event. Unlike staffs and sponsorships, this resource lives at the top level (/v4/event_submissions) and references its event by event_id.

Endpoints

Method	Path	What it does
`GET`	`/v4/event_submissions`	List event submissions
`GET`	`/v4/event_submissions/{id}`	Get one submission
`POST`	`/v4/event_submissions`	Create a submission
`PATCH` / `PUT`	`/v4/event_submissions/{id}`	Update a submission
`DELETE`	`/v4/event_submissions/{id}`	Delete a submission

Fields

event_id — the event the project was submitted to. Required to associate the submission with an event.
project_id — the project being submitted.
submitter_id — the user who submitted it.
submitted_at — when it was submitted. Send as an ISO 8601 string on create/update; returned as a Unix timestamp.
csvifier_id — an integer reference to an import batch, when the record came from a bulk upload.
project, submitter, event — the associated project, submitter, and event records.

Read-only response fields include id, created_at, and updated_at.

Expanding and filtering

expand[] supports project, submitter, and event. List filtering is available on project_id, event_id, submitter_id, submitted_at, created_at, and updated_at. For example:

GET /v4/event_submissions?event_id[eq]=evt_123&submitted_at[gte]=2026-03-14

Example

POST /v4/event_submissions

{
  "event_id": "evt_123",
  "project_id": "prj_456",
  "submitter_id": "usr_789"
}

V4 API overview
Making requests — pagination, filtering, expand[], and errors.
Authentication — auth methods and scopes.
Participations — create and update participations.
Challenges — the challenges linked by event challenges.
MLH Sponsorships — MLH-level sponsorships (distinct from per-event sponsorships).

Events​

Endpoints​

Fields​

Expanding related data​

Filtering​

GET /v4/events/identify​

Example​

Event Applications​

Endpoints​

Fields​

Expanding and filtering​

GET /v4/event_applications/identify​

Example​

Event Staffs​

Endpoints​

Fields​

Expanding and filtering​

Example​

Event Sponsorships​

Endpoints​

Fields​

Expanding and filtering​

POST /v4/events/sponsorships (create from OHQ)​

Example​

Event Participations​

Endpoints​

Fields (read-only here)​

Example​

Event Challenges​

Endpoints​

Fields​

Example​

Event Submissions​

Endpoints​

Fields​

Expanding and filtering​

Example​

Related​

Events

Endpoints

Fields

Expanding related data

Filtering

`GET /v4/events/identify`

Example

Event Applications

Endpoints

Fields

Expanding and filtering

`GET /v4/event_applications/identify`

Example

Event Staffs

Endpoints

Fields

Expanding and filtering

Example

Event Sponsorships

Endpoints

Fields

Expanding and filtering

`POST /v4/events/sponsorships` (create from OHQ)

Example

Event Participations

Endpoints

Fields (read-only here)

Example

Event Challenges

Endpoints

Fields

Example

Event Submissions

Endpoints

Fields

Expanding and filtering

Example

Related