Skip to content

Events

Events may be created or updated. The request and response bodies are the same in both situations.

If you don't provide an external ID when creating an event, you must store the ID that is returned in order to update. Note that we do not support partial updates for required attributes, required attributes must be supplied at all times.

Attributes

externalId

string optional

Your own event ID if you are cross-posting from another system. This must be consistent across requests and unique within your channel.

Warning

If present, this will always take precedence over our ID when updating events.

channelId

integer optional

The (numerical) channel ID to post to, if different from the primary channel ID as per authentication. This only applies to superclubs and the given channel ID must be either the super club, or one of its direct sub clubs. Aggregated clubs are not allowed.

title

string required

Title of the event in question. Note that titles do not have to be unique and we do not prevent duplication.

type

int required

This must be a valid event type ID, see event-types.

contactEmail

string required

Must be a correctly formatted, valid email address.

startedAt

DateTime required

Note

This is stored as-is and should be the event's local date and time. Our systems and app will use the given location to then convert these to a members' own timezone where applicable.

Required unless isSelfPacedCourse is true.

endedAt

DateTime required

Note

This is stored as-is and should be the event's local date and time. Our systems and app will use the given location to then convert these to a members' own timezone where applicable.

Required unless isSelfPacedCourse is true.

isVip

bool required

Whether this event requires the feature flag for event access to be set. When set to true, members will be prompted to upgrade their membership if their feature flag was returned as false by your SSO.

externalUrl

url optional

Must be a valid URL if provided. Must not be provided if tickets is present.

If set to null this will create a free event on our platform.

You can use the following placeholders:

  • ~id~: the member's ID as returned by your authentication system
  • ~email~: the member's email address as returned by your authentication system
  • ~eventId~: our internal event ID
  • ~token~: the access token obtained from your SSO

As an example, https://the-dots.com?user_id=~id~&access_token=~token~ is transformed to https://the-dots.com?user_id=1234&access_token=some_token_value before we load it.

isPaid

bool required: externalUrl is not empty

Whether this is a paid event. This is used to display the correct label in any event listings.

For on-platform events, you may omit this because we will infer this automatically.

receivesRsvpWebhooks

bool required: externalUrl is not empty

Warning

This value must be set correctly at all times. If set to true without actually calling the endpoint, this may degrade members' experience!

Whether webhooks to confirm RSVPs are set up for this event. If set to false, communication around the event will be geared towards members' interest in the event, rather than them going to the event.

image

string required: on create

Must be a valid URL to an image. It may be omitted when updating an event. We assume it is a new image if provided, so it is retrieved and stored whenever it is provided.

Recommendation is using a 2:1 ratio, minimum 1400x700px.

location

string required

This must be a valid Google Places ID. This is used to display an approximate location, with address and addressDetails allowing you to display the location a textual format. The location does not have to be the exact address, but we do recommend resolving the address to a Google Place. Note that we also use the timezone from this location to display the correct start/end times to members.

description

string required

A description of the event. May contain linebreaks.

host

int required

Must be a valid Page ID, see pages.

cohosts

array optional

Default: []

Each value in this array must be a valid Page ID, see pages.

isSelfPacedCourse

bool optional

Default: false

Indicates a self-paced course which has no formal start or end dates/times.

isVirtual

bool optional

Default: false

Indicates a virtual (online) event.

isTicketless

bool optional

Default: false

Whether the event is ticketless, meaning people can show up at will.

capacity

int optional

Default: null

If not provided or set to 0, the event will allow unlimited registrations.

This is the total available capacity for this event (in our system). Availability for the event will be calculated by subtracting the number of RSVPs / tickets sold; if receivesRsvpWebhooks is enabled, only confirmed RSVPs will count towards capacity.

When updating, this value can not be set to less than the number of RSVPs already registered.

address

string optional

Default: null

May not be longer than 255 characters. Note that location is not resolved from this, as resolving addresses requires human input.

addressDetails

string optional

Default: null

This may be provided to clarify the address. For example, clarifying routes or rooms within buildings.

publishedAt

DateTime optional

Default: "now"

Note

The event's location is not taken into account for this attribute. It will always be interpreted as UTC.

This may be used to schedule events ahead of time. Has no effect on start or end dates, only on visibility. If not provided, the event will be published immediately.

ticketTypes

array optional on create

Note

This is a feature that is made available upon request, and requires a fully configured Stripe account to be connected to your channel. Once enabled, all on-platform events require ticket types to be specified (including free events!).

This feature is also mutually exclusive with externalUrl - only one may be provided.

An array of objects specifying the ticket type. After an event has been created, adding or updating ticket types must be done through their dedicated endpoints.

  • string optional on update id: the ticket ID generated by our systems. Must be present for updates if externalId is not provided.
  • string optional externalId: your own ticket ID if you are cross-posting from another system. This must be consistent across requests and unique within your channel.
  • string required title: the title to be displayed to your members when they go to RSVP.
  • int required purchaseLimit: the maximum number of tickets a member may purchase of this ticket type
  • bool required requiresVipFlag: whether this ticket type is available for VIP members only

  • int required quantity: number of tickets available (inventory) of this type. May only be increased on updates.

    Note

    The quantity for all tickets combined may exceed event capacity; this is recommended, actually.

    Sales are still controlled by the event's capacity. Once the total number of tickets sold hits that capacity, additional inventory of tickets will no longer be available for purchase.

  • integer required price: Price of the ticket in the smallest denomination for the currency of the event (commonly pennies/cents)

    Warning

    Decimal numbers (floating point) are not accepted. The correct value for GBP 9.95 (same for USD or EUR) is 995.

Ticket types may be updated through event update requests.

currency

string required with ticketTypes

Three-letter ISO4217 code, as supported by Stripe

taxName

string required with ticketTypes

Name of the sales tax at the event's location; e.g. VAT for the UK, MwSt. for Germany, et cetera. Must be provided even for free ticketed events.

taxPercentage

int | float required with ticketTypes

Sales tax percentage at the event's location. May be provided as a decimal or integer.

Endpoints

Create (unticketed, on-platform)

HTTP
POST /channels/events.create
Content-Type: application/json
Authorization: Channel <Api Key>
X-Channel: <Channel Identifier>

{
    "title": "Chinese New Year Celebration",
    "type": 1,
    "contactEmail": "events@the-dots.com",
    "startedAt": "2026-02-17 00:00",
    "endedAt": "2026-02-17 03:00",
    "isVip": false,
    "image": "https://my-website.com/images/event-123.jpg",
    "location": "ChIJuSwU55ZS8DURiqkPryBWYrk",
    "description": "Chinese New Year celebration, in Beijing",
    "host": 1,
    "cohosts": [
        2,
        3
    ],
    "isSelfPacedCourse": false,
    "isVirtual": false,
    "isTicketless": false,
    "capacity": 100,
    "address": "Tiananmen Square",
    "addressDetails": "Some further details",
    "publishedAt": "now"
}
JSON
{
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": 201,
    "data": {
        "id": 1,
        "externalId": null
    }
}

Create (off-platform)

HTTP
POST /channels/events.create
Content-Type: application/json
Authorization: Channel <Api Key>
X-Channel: <Channel Identifier>

{
    "externalId": "event-123",
    "title": "Chinese New Year Celebration",
    "type": 1,
    "contactEmail": "events@the-dots.com",
    "startedAt": "2026-02-17 00:00",
    "endedAt": "2026-02-17 03:00",
    "isVip": false,
    "receivesRsvpWebhooks": true,
    "isPaid": false,
    "externalUrl": "https://my-website.com/events/123",
    "image": "https://my-website.com/images/event-123.jpg",
    "location": "ChIJuSwU55ZS8DURiqkPryBWYrk",
    "description": "Chinese New Year celebration, in Beijing",
    "host": 1,
    "cohosts": [
        2,
        3
    ],
    "isSelfPacedCourse": false,
    "isVirtual": false,
    "isTicketless": false,
    "capacity": 100,
    "address": "Tiananmen Square",
    "addressDetails": "Some further details",
    "publishedAt": "now"
}
JSON
{
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": 201,
    "data": {
        "id": 1,
        "externalId": "event-123"
    }
}

Create (ticketed, on-platform)

HTTP
POST /channels/events.create
Content-Type: application/json
Authorization: Channel <Api Key>
X-Channel: <Channel Identifier>

{
    "externalId": "event-123",
    "title": "Chinese New Year Celebration",
    "type": 1,
    "contactEmail": "events@the-dots.com",
    "startedAt": "2026-02-17 00:00",
    "endedAt": "2026-02-17 03:00",
    "isVip": false,
    "image": "https://my-website.com/images/event-123.jpg",
    "location": "ChIJuSwU55ZS8DURiqkPryBWYrk",
    "description": "Chinese New Year celebration, in Beijing",
    "host": 1,
    "cohosts": [
        2,
        3
    ],
    "isSelfPacedCourse": false,
    "isVirtual": false,
    "isTicketless": false,
    "capacity": 100,
    "address": "Tiananmen Square",
    "addressDetails": "Some further details",
    "publishedAt": "now",
    "ticketTypes": [
        {
            "externalId": "ticket-100",
            "title": "General Admission",
            "price": 1000,
            "quantity": 100,
            "purchaseLimit": 3,
            "requiresVipFlag": false
        },
        {
            "externalId": "ticket-101",
            "title": "VIP Free Entry",
            "price": 0,
            "quantity": 100,
            "purchaseLimit": 1,
            "requiresVipFlag": true
        }
    ]
}
JSON
{
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": 201,
    "data": {
        "id": 1,
        "externalId": "event-123",
        "tickets": [
            {"id": 1, "externalId": "ticket-100"},
            {"id": 2, "externalId": "ticket-101"}
        ]
    }
}

Update w/ Dots ID

HTTP
POST /channels/events.update/{id}
Content-Type: application/json
Authorization: Channel <Api Key>
X-Channel: <Channel Identifier>

{
    "title": "Chinese New Year Celebration",
    "type": 1,
    "contactEmail": "events@the-dots.com",
    "startedAt": "2026-02-17 00:00",
    "endedAt": "2026-02-17 03:00",
    "isVip": false,
    "receivesRsvpWebhooks": true,
    "isPaid": false,
    "externalUrl": "https://my-website.com/events/123",
    "image": "https://my-website.com/images/event-123.jpg",
    "location": "ChIJuSwU55ZS8DURiqkPryBWYrk",
    "description": "Chinese New Year celebration, in Beijing",
    "host": 1,
    "cohosts": [
        2,
        3
    ],
    "isSelfPacedCourse": false,
    "isVirtual": false,
    "isTicketless": false,
    "capacity": 100,
    "address": "Tiananmen Square",
    "addressDetails": "Some further details",
    "publishedAt": "now"
}
JSON
{
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": 200,
    "data": {
        "id": 1,
        "externalId": null
    }
}

Update w/ external ID

HTTP
POST /channels/events.update
Content-Type: application/json
Authorization: Channel <Api Key>
X-Channel: <Channel Identifier>

{
    "externalId": "event-123",
    "title": "Chinese New Year Celebration",
    "type": 1,
    "contactEmail": "events@the-dots.com",
    "startedAt": "2026-02-17 00:00",
    "endedAt": "2026-02-17 03:00",
    "isVip": false,
    "receivesRsvpWebhooks": true,
    "isPaid": false,
    "externalUrl": "https://my-website.com/events/123",
    "image": "https://my-website.com/images/event-123.jpg",
    "location": "ChIJuSwU55ZS8DURiqkPryBWYrk",
    "description": "Chinese New Year celebration, in Beijing",
    "host": 1,
    "cohosts": [
        2,
        3
    ],
    "isSelfPacedCourse": false,
    "isVirtual": false,
    "isTicketless": false,
    "capacity": 100,
    "address": "Tiananmen Square",
    "addressDetails": "Some further details",
    "publishedAt": "now"
}
JSON
{
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": 200,
    "data": {
        "id": 1,
        "externalId": "event-123"
    }
}