Skip to content
BuilderBase API DOCS
Back to home
Book a call

Registrations

Registrations connect participants to events and super events.

To onboard third parties at scale (people who may not yet have a BuilderBase account), use the Onboarding section below - POST /events/:id/register can only register the key’s own user.

Read

List registrations GET /events/:eventId/registrations 
{
  "data": {
    "registrations": [
      {
        "id": "9a1c3e5f-7b2d-4068-a9e4-1c3b5d7f9028",
        "event_id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16",
        "user_id": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94",
        "status": "accepted",
        "name": "Alice Rivera",
        "email": "alice.rivera@northwind.io",
        "evaluation_score": 8.5,
        "evaluation_recommendation": "accept"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 142,
      "totalPages": 3
    }
  }
}
List super event registrations GET /super-events/:superEventId/registrations 
{
  "data": {
    "registrations": [
      {
        "id": "9a1c3e5f-7b2d-4068-a9e4-1c3b5d7f9028",
        "event_id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16",
        "user_id": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94",
        "status": "accepted",
        "name": "Alice Rivera",
        "email": "alice.rivera@northwind.io"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 142,
      "totalPages": 3
    }
  }
}
Get registration GET /registrations/:id 
{
  "data": {
    "registration": {
      "id": "9a1c3e5f-7b2d-4068-a9e4-1c3b5d7f9028",
      "event_id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16",
      "user_id": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94",
      "status": "accepted",
      "checkin_token": "ci_7Kd92mAx4Qp",
      "answers_json": {
        "github": "https://github.com/arivera",
        "track": "autonomous-agents"
      },
      "users": {
        "id": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94",
        "name": "Alice Rivera",
        "email": "alice.rivera@northwind.io",
        "linkedin_url": "https://linkedin.com/in/alicerivera",
        "github_url": "https://github.com/arivera"
      },
      "events": {
        "id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16",
        "name": "Autonomous Agents Track",
        "slug": "autonomous-agents"
      }
    }
  }
}

Write

Register (key's own user) POST /events/:eventId/register 
{
  "data": {
    "id": "9a1c3e5f-7b2d-4068-a9e4-1c3b5d7f9028",
    "event_id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16",
    "user_id": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94",
    "status": "pending",
    "checkin_token": "ci_7Kd92mAx4Qp"
  }
}
Update registration answers PATCH /registrations/:id 
{
  "data": {
    "id": "9a1c3e5f-7b2d-4068-a9e4-1c3b5d7f9028",
    "answers_json": {
      "github": "https://github.com/arivera",
      "track": "autonomous-agents"
    }
  }
}
Update registration status PATCH /registrations/:id/status 
{
  "data": {
    "updated": true,
    "status": "accepted"
  }
}

Onboarding (at scale)

For getting people into your hackathon programmatically - whether they already have an account or not. Use this when your registration system lives outside BuilderBase (e.g. Tally, a custom form, an internal CRM) and you push selected applicants in. New emails get a magic link; existing onboarded users are enrolled immediately.

Onboard a participant POST /super-events/:slug/participants

The behaviour depends on whether the email already belongs to a BuilderBase account:

HTTPBodyWhen
201{ "status": "enrolled", "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94" }Email already belongs to an onboarded user - enrolled immediately with status='accepted'.
201{ "status": "invited", "email": "alice.rivera@northwind.io" }Email is new or onboarding unfinished - a magic link is sent; after they click it the account is created and auto-enrolled.
200{ "status": "already_invited", "email": "alice.rivera@northwind.io" }A pending invite already exists. Idempotent.
200{ "status": "already_enrolled", "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94" }User already has an accepted registration. Idempotent.
Assign / move builder to track PATCH /super-events/:superEventId/team-management/builders/:userId/track

Without targetTeamId (track move only):

{
  "data": {
    "result": {
      "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94",
      "targetEventId": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16"
    }
  }
}

With targetTeamId (also joins a team):

{
  "data": {
    "result": {
      "teamId": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53",
      "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94"
    }
  }
}

Check-in

Records attendance for a registered participant. The token is the registration’s checkin_token (from Get registration above, or the participant’s QR code) - this is the endpoint a kiosk hits after scanning.

Scan a check-in POST /checkin-points/:pointId/scan

The endpoint returns one of several shapes depending on the outcome. Handle all of them in a kiosk client:

ScenarioHTTPBody
First successful check-in201{ "data": { "checked_in": true, "checked_in_at": "2026-07-14T09:00:00.000Z", "registration_id": "9a1c3e5f-7b2d-4068-a9e4-1c3b5d7f9028", "point_name": "Main Entrance", "point_type": "attendance" } }
Already checked in (attendance)200{ "data": { "already_checked_in": true, "checked_in_at": "2026-07-14T09:00:00.000Z" } }
Doorkeeper re-scan200{ "data": { "verified": true, "first_check_in_at": "2026-07-14T09:00:00.000Z" } }
Milestone gate200{ "data": { "requires_milestone_submission": true, "milestone_requirements": [...], "team_id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "team_name": "Beat Wizards" } }
Invalid token404{ "code": "INVALID_TOKEN" }
Registration not accepted403{ "code": "NOT_ACCEPTED" }
Window not yet open400{ "code": "TOO_EARLY" }
Window closed400{ "code": "TOO_LATE" }
Check-in point not found404{ "code": "POINT_NOT_FOUND" }
Manual method, non-organizer403{ "code": "ORGANIZER_REQUIRED" }
Milestone point, no team400{ "code": "NO_TEAM" }

On the milestone gate the check-in is not recorded - submit the milestone, then re-scan.