Events app — reference

What the app is#

Events runs the whole lifecycle of an event inside HubSpot: an organiser creates the event as a CRM record, visitors register through an embed on the website, the app issues each attendee a QR ticket by email, and staff scan that ticket at the door. Capacity, waitlists and automatic promotion are handled for you; every registration is a CRM record, so reporting, workflows and lists work on it the way they work on anything else in the portal.

Overview#

The Events app stores event data in two HubSpot custom CRM objects: events and event_registrations. The worksby.design API provides endpoints for listing events, managing registrations, and checking attendees in. Events themselves are created and edited directly in HubSpot CRM (not via this API) — see Creating and managing events below.

Base URL: https://api.worksby.design/apps/events/

All responses are JSON. Successful responses include "success": true. Errors include "error": "<message>" and an appropriate HTTP status code.

Authentication#

There are five auth policies, not one. Which applies to a given endpoint is listed in Endpoint index below, and that table is generated from the same manifest the service's own route-coverage test enforces — so it cannot drift from the running code.

Every request carries portalId — the numeric HubSpot portal ID. For GET pass it as a query parameter; for POST include it in the JSON body. No API key is ever passed by the caller.

The server validates that the portal has completed the OAuth install flow and holds a stored access token. If not, the endpoint returns 403 with { "error": "Portal <id> not authorised for events" }. If the licence has expired it returns 403 with { "code": "LICENSE_INACTIVE" }.

Contact sessions — read this before integrating#

Five endpoints require a proven contact and will not accept a contactId in the body as proof of identity: check-in-by-qr, door-events, my-event-registration, fetch-user-registrations and update-registration. For the member-scoped three, the session token's contact overrides any id you submit, so a caller can only ever read or change their own registrations; the two scanner endpoints use the session to prove staff, not to scope data.

Mint the token with scan-session. It is an HMAC token valid for one hour.

Endpoint index#

30 endpoints — 9 public, 5 member, 13 admin, 3 server-to-server.

Endpoints marked Admin or Server-to-server are part of the app's operation, not its integration contract: they are listed for completeness and are not documented in detail below.

Custom object — events#

Created automatically on first install. The name property is unique and acts as the primary identifier across all API calls and navigation links. Object type name: events. The numeric objectTypeId is portal-specific and resolved by the backend at runtime — callers never need it.

Custom object — event_registrations#

One record per attendee per event. Created by create-registration. Each registration is associated to its event and (optionally) to a HubSpot contact.

Associations#

Five association labels are created automatically on install. Label names are stable contracts — the backend resolves portal-specific numeric type IDs at runtime by matching on the label name. Do not rename these labels in HubSpot.

Endpoints#

GET /apps/events/license-status#

Check whether a portal has an active Events license. Does not require OAuth install — safe to call before the install flow.

Query parameters

Response

{ "licensed": true }

POST /apps/events/fetch-events#

Return a list of published events, sorted by start_datetime ascending. By default returns only upcoming events (start date in the future).

Request body

The endpoint pages through HubSpot results for you (100 per page, up to 10 pages) and returns the full set in one response — there is no cursor to follow.

Response

{
  "success": true,
  "total": 3,
  "events": [
    {
      "id": "12345678",
      "name": "Monthly Member Webinar",
      "url_slug": "monthly-member-webinar",
      "start_datetime": "2026-06-15T14:00:00.000Z",
      "end_datetime": "2026-06-15T16:00:00.000Z",
      "event_type": "webinar",
      "event_status": "published",
      "event_tags": "online;members",
      "is_online": "true",
      "location_name": "Online via Microsoft Teams",
      "city": null,
      "country": null,
      "price_amount": "0",
      "price_currency": "EUR",
      "capacity_total": "500",
      "capacity_current": "12",
      "image_featured": "https://images.unsplash.com/...",
      "image_thumbnail": "https://images.unsplash.com/..."
    }
  ]
}

POST /apps/events/fetch-event-details#

Fetch full details for a single event. Looks up the event by url_slug, then name (exact match), then name (partial match) — the first match wins.

This is the public event page read, so the event body is visible to anonymous callers. The registrations array is not: it is scoped to the caller's own proven session contact.

Request body

Response

{
  "success": true,
  "event": {
    "id": "12345678",
    "name": "Monthly Member Webinar",
    "description": "Our regular online gathering...",
    "start_datetime": "2026-06-15T14:00:00.000Z",
    "capacity_total": "500",
    "capacity_current": "12",
    "...": "...all event properties..."
  },
  "registrations": [
    {
      "id": "98765432",
      "attendee_name": "Sarah Johnson",
      "email": "sarah.johnson@example.com",
      "registration_status": "confirmed",
      "payment_status": "paid",
      "qr_code": "EVT-ABC123DEF456",
      "check_in_datetime": null,
      "...": "...all registration properties..."
    }
  ]
}

Above, registrations holds the session contact's own registration. An anonymous caller gets the same event object and "registrations": [].

POST /apps/events/scan-session#

Mint the contact-session token the member-scoped endpoints require. The caller is already an authenticated CMS member; this verifies their email against the CRM contact before issuing.

Request body

Every refusal returns the same 403 Identity verification failed, whether the email was absent, wrong, or the contact id does not exist. That is deliberate: a distinguishable response would let a caller discover which contact ids are real.

Response

{
  "success": true,
  "sessionToken": "eyJwb3J0YWxJZCI6...",
  "sessionExpiry": 1786351200000,
  "keyringScannerUrl": null
}

The token is valid for one hour; sessionExpiry is epoch milliseconds. keyringScannerUrl is the configured hand-off target for the staff scanner, or null when no sibling app is configured.

POST /apps/events/my-event-registration#

The signed-in member's own ticket(s) for one event, plus the online join link. This is the endpoint to use for "my ticket" surfaces — never fetch-event-details.

Request body

Response

{
  "success": true,
  "registrations": [
    {
      "id": "98765432",
      "attendee_name": "Sarah Johnson",
      "email": "sarah.johnson@example.com",
      "registration_status": "confirmed",
      "attendance_status": "not_arrived",
      "ticket_type": "standard",
      "qr_code": "EVT-ABC123DEF456",
      "payment_status": "paid"
    }
  ],
  "onlineMeetingUrl": "https://teams.microsoft.com/l/meetup-join/..."
}

onlineMeetingUrl is returned only when the member holds a non-cancelled ticket; otherwise null. Registrations are matched by the proven contact's email, so a member with no ticket gets [] rather than an error.

POST /apps/events/event-stats#

Aggregate figures for one event. Counts only — no attendee PII, which is why it is safe for a public capacity bar as well as the organiser dashboard.

Request body

Response

{
  "success": true,
  "stats": {
    "eventName": "Annual Member Conference",
    "capacityTotal": 500,
    "confirmed": 312,
    "waitlisted": 18,
    "pending": 4,
    "cancelled": 9,
    "total": 343,
    "active": 334,
    "checkedIn": 287,
    "noShow": 2,
    "notArrived": 25,
    "spotsRemaining": 188,
    "checkInRate": 92,
    "byEventTicketType": { "standard": 280, "vip": 54 },
    "byPaymentStatus": { "paid": 300, "free": 34 },
    "revenue": { "amount": 18750.00, "currency": "EUR" },
    "registrationsByDay": [{ "date": "2026-06-01", "count": 12 }],
    "arrivalsByHour": [{ "time": "2026-06-15T09:00", "count": 63 }]
  }
}

spotsRemaining is null for an uncapped event (capacity_total of 0). checkInRate is a whole-number percentage of confirmed. notArrived is confirmed - checkedIn, floored at zero.

POST /apps/events/fetch-user-registrations#

Find all event IDs that a specific contact is registered for. Matches by contact email address via the event_registrations object.

Request body

Response

{
  "success": true,
  "eventIds": ["12345678", "87654321"]
}

POST /apps/events/create-registration#

Register an attendee for an event. Creates the event_registrations record, creates or updates the HubSpot contact, and creates all three association links (event → registration, contact → registration, contact → event). Increments capacity_current on the event.

Request body

formData fields

Response

{
  "success": true,
  "registration": {
    "id": "98765432",
    "qr_code": "EVT-ABC123DEF456",
    "email": "sarah.johnson@example.com"
  }
}

POST /apps/events/update-registration#

Update a single editable property on an existing registration. Used for inline attendee detail corrections.

Request body

Response

{ "success": true }

POST /apps/events/check-in-by-qr#

Look up a registration by QR code and optionally check the attendee in. Returns an access decision that drives the check-in UI: grant entry, deny, flag as already checked in, or report an error.

Requires a contact session — mint one with scan-session. Without it the endpoint would hand attendee PII to anyone holding a portal ID and a QR string.

Request body

Access decisions

A registration that carries no event association is never refused on scope grounds — that's a data defect on the portal, not a reason to turn an attendee away. The decision proceeds as if unscoped and an EVENT_UNKNOWN warning is returned instead.

Warnings

warnings is advisory and never changes the decision. Each entry carries a code and a server-authored message; render the message verbatim for any code you don't recognise, since new codes can appear before a scanner UI is updated.

On a DENY, denyReason carries { code, message } — REGISTRATION_CANCELLED, ON_WAITLIST, REGISTRATION_PENDING, PAYMENT_PENDING, PAYMENT_REFUNDED, PAYMENT_SUSPENDED, or NOT_GRANTED. It is null for every other decision. Same rule as warnings: render your own copy for codes you know, the server's message for ones you don't.

Time is only ever a warning — entry is never refused on the clock alone. The grace either side is operator-tunable per deployment.

Response

{
  "success": true,
  "accessDecision": "GRANT",
  "checkedIn": true,
  "warnings": [
    { "code": "LATE", "minutes": 300, "message": "This event ended 5 h ago." }
  ],
  "doorEventId": "551",
  "registration": {
    "id": "98765432",
    "attendeeName": "Sarah Johnson",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "email": "sarah.johnson@example.com",
    "company": "Acme Corp",
    "jobTitle": "Product Manager",
    "eventTicketType": "standard",
    "registrationStatus": "confirmed",
    "paymentStatus": "paid",
    "attendanceStatus": "checked_in",
    "checkInDatetime": "2026-06-15T09:32:00.000Z",
    "specialRequirements": null
  },
  "event": {
    "id": "551",
    "name": "Annual Member Conference",
    "startDatetime": "2026-06-15T09:00:00.000Z",
    "endDatetime": "2026-06-15T17:00:00.000Z"
  }
}

POST /apps/events/door-events#

The short list of events a door might be staffing: published events starting within the last 48 hours or the next 30 days, oldest first. Feeds the scanner's "which event are you staffing?" picker, whose selection becomes eventId on check-in-by-qr.

Requires the same contact session as check-in-by-qr. The payload is published event names and times — the same data fetch-events serves publicly — and carries no attendee information.

Request body

Response

{
  "success": true,
  "events": [
    {
      "id": "551",
      "name": "Annual Member Conference",
      "startDatetime": "2026-06-15T09:00:00.000Z",
      "endDatetime": "2026-06-15T17:00:00.000Z",
      "locationName": "Main Hall",
      "live": true
    }
  ]
}

live is true when now falls inside the door window (start minus the early grace, to end plus the late grace) — the same window that produces the EARLY/LATE warnings, so a scanner's auto-selection and the warning it later shows can never disagree about what "now" means. An event with no start_datetime is never live.

Creating and managing events#

Events are created and edited directly via the HubSpot CRM API — this worksby.design API does not expose a create/update event endpoint. Use the standard HubSpot /crm/v3/objects/{objectTypeId} endpoints with the events custom object.

Resolving the objectTypeId#

HubSpot assigns a different numeric objectTypeId to the events custom object on each portal. To resolve it, fetch all schemas and find the one whose name field equals "events":

GET https://api.hubapi.com/crm/v3/schemas
Authorization: Bearer {access_token}

// In the response, find:
results.find(s => s.name === 'events').objectTypeId
// → e.g. "2-12345678"

Creating an event#

Once you have the objectTypeId, create an event with a POST to /crm/v3/objects/{objectTypeId}:

POST https://api.hubapi.com/crm/v3/objects/{objectTypeId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "properties": {
    "name": "Monthly Member Webinar",
    "url_slug": "monthly-member-webinar",
    "description": "Our regular online gathering for members.",
    "meta_description": "Free monthly online webinar — live panel and open Q&A.",
    "highlights": "Live panel, member updates, exclusive content.",
    "event_type": "webinar",
    "event_status": "published",
    "start_datetime": "2026-07-15T14:00:00.000Z",
    "end_datetime": "2026-07-15T16:00:00.000Z",
    "is_online": "true",
    "location_name": "Online via Microsoft Teams",
    "price_amount": "0",
    "price_currency": "EUR",
    "capacity_total": "500",
    "capacity_current": "0",
    "features": "recording",
    "registration_mode": "form",
    "image_featured": "https://images.unsplash.com/photo-...",
    "image_thumbnail": "https://images.unsplash.com/photo-..."
  }
}

Required properties for a visible event#

At minimum, set these properties for an event to appear in fetch-events results:

• name — must be unique; this is the event identifier
• event_status: "published" — draft and cancelled events are excluded
• start_datetime — must be in the future (unless upcomingOnly: false)

Updating an event#

PATCH https://api.hubapi.com/crm/v3/objects/{objectTypeId}/{eventId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "properties": {
    "event_status": "cancelled"
  }
}

Writing registrations directly (sample data)#

To seed demo attendees, create event_registrations records directly via the CRM API rather than calling create-registration (which also matches contacts, enforces capacity, and may send email). Resolve the event_registrations objectTypeId the same way as for events.

POST https://api.hubapi.com/crm/v3/objects/{registrationsObjectTypeId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "properties": {
    "attendee_name": "Sarah Johnson",
    "first_name": "Sarah",
    "last_name": "Johnson",
    "email": "sarah.johnson@example.com",
    "registration_date": "2026-06-01T10:00:00.000Z",
    "registration_status": "confirmed",
    "attendance_status": "not_arrived",
    "payment_status": "free",
    "ticket_type": "standard",
    "qr_code": "EVT-ABC123DEF456",
    "purchaser_email": "sarah.johnson@example.com",
    "purchaser_name": "Sarah Johnson"
  }
}

Then link the record. Resolve each numeric association type ID by label via GET /crm/v4/associations/{from}/{to}/labels, then create with batch/create. Use the field name from (not _from) or the link is silently dropped:

• events → event_registrations · label Event Registrations
• contacts → event_registrations · label Registered Attendee (the attendee)
• contacts → event_registrations · label Purchaser (the buyer — same contact as the attendee for self-registration)
• contacts → events · label Registered

Integration seams#

Events is one of three of our apps that share a portal, and each seam is deliberately thin — a documented contract, never shared code.

Neither seam is required. Events runs perfectly well as the only one of the three on a portal; free events need no Commerce, and door staff can use the Events scanner directly.