Skip to main content

Imports, Webhooks, and Banner Notices

This page covers three smaller parts of the V4 API: Imports (bulk data import jobs), Webhooks (event receivers), and Banner Notices (site-wide notice lookups).

All requests are authenticated and follow the shared conventions for pagination, filtering, expanding, and errors — see Authentication and Making requests. The examples below omit the Authorization header for brevity.

Imports​

An import is a bulk data import job. It records where a batch of data came from (an external source), what kind of records it brought in, and how far along the job is. Use imports to load data such as registrations, check-ins, or project submissions from another system into MLH, and to track whether that job is still pending, has been processed, or errored.

Endpoints​

MethodPathDoes
POST/v4/importsCreate an import
PATCH / PUT/v4/imports/{id}Update an existing import
GET/v4/imports/identifyLook up an import by a user identifier

Fields​

When you create or update an import, you can set the following fields. Send timestamp fields (created_at, updated_at, processed_at, errored_at) as ISO 8601 datetime strings on the request. In responses, those same fields are returned as Unix timestamps (integers, seconds since the epoch).

FieldRequiredWhat it isExample
import_typeOptionalThe kind of records this job imports. One of registration, checkin, submission, project."registration"
statusOptionalWhere the job is in its lifecycle. One of pending, processed, errored."pending"
external_source_typeOptionalThe type of system the data came from."typeform"
external_source_idOptionalThe identifier of the record or batch in that external system."form_abc123"
eventOptionalThe event this import is associated with."hackathon-2026"
import_line_itemsOptionalThe individual line items that make up this import.["li_1", "li_2"]
processed_atOptionalWhen the job finished processing. Send as an ISO 8601 string; returned as a Unix timestamp."2026-08-19T14:00:00Z"
errored_atOptionalWhen the job errored, if it did. Send as an ISO 8601 string; returned as a Unix timestamp."2026-08-19T14:05:00Z"

Read-only fields (returned in responses; set by MLH, not by you):

  • id — the import's unique identifier.
  • created_at — when the import was created (Unix timestamp).
  • updated_at — when the import was last changed (Unix timestamp).

Identify an import​

GET /v4/imports/identify looks up an import for a given user, using an email address or phone number rather than an import id. It takes these query parameters:

ParameterRequiredWhat it does
identifierRequiredThe email address or phone number to identify the user by.
auto_createOptionalIf true, automatically create the user when no match is found. Boolean.

The response is a single import object with the same fields described above (timestamps as Unix integers), including its import_type, status, external_source_type, external_source_id, event, and import_line_items.

Scopes​

Requests use the standard V4 authentication scopes described in Authentication. Request only the scopes your integration needs.

Example​

Create an import:

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

{
  "import_type": "registration",
  "status": "pending",
  "external_source_type": "typeform",
  "external_source_id": "form_abc123",
  "event": "hackathon-2026"
}

Identify an import by email, creating the user if needed:

GET /v4/imports/identify?identifier=jane@example.com&auto_create=true

Webhooks​

The Webhooks tag is reserved for webhook receiver endpoints — endpoints that receive event notifications. At this time the API spec declares the Webhooks group but does not publish any webhook operations, event names, or payload schemas. There is no webhooks block, and there are no request or response shapes to document yet.

The detailed webhook event catalog is not yet published. This section will be expanded once those events and payloads are defined in the spec. Until then, treat webhooks as undocumented rather than assuming any particular event names or formats.

Banner notices are the notice messages MLH can surface to users (for example, a site-wide banner). The lookup endpoint lets your integration fetch the banner notice information that applies to the current request.

Endpoint​

MethodPathDoes
GET/v4/banner_notices/lookupPerform a lookup on banner notices

GET /v4/banner_notices/lookup performs a lookup and returns a JSON object describing the applicable banner notice(s). The spec does not declare specific query parameters for this endpoint, and the response is a generic JSON object rather than a fixed schema, so inspect the returned body directly for the fields you need.

Like all V4 endpoints, this can return 401 (not authenticated) or 404 (not found) — see Making requests for the shared error format.

Scopes​

Requests use the standard V4 authentication scopes described in Authentication.

Example​

GET /v4/banner_notices/lookup