Events App —
API Reference.

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 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

All endpoints except GET /license-status require the portal to have the Events app installed and a valid active license. Authentication is handled automatically — no API key is passed by the caller.

Every request must include portalId — the numeric HubSpot portal ID. For GET requests pass it as a query parameter. For POST requests include it in the JSON body.

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 license has expired it returns 403 with { "code": "LICENSE_INACTIVE" }.

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

{ "licensed": true }

{
  "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/..."
    }
  ]
}

{
  "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...
    }
  ]
}

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

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

{ "success": true }

{
  "success": true,
  "accessDecision": "GRANT",
  "checkedIn": true,
  "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": {
    "name": "Annual Member Conference",
    "startDatetime": "2026-06-15T09:00:00.000Z"
  }
}

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