Events API References

Get All Events

URL: https://api.gradual-api.com/public-api/v1/events

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200
title, string, optional, support partial matches
startDate, string, optional, format: YYYY-MM-DD, date will be padded to the start of the day. If a startDate is specified, the response will include events with a start time later than 00:00 of the provided startDate.
endDate, string, optional, format: YYYY-MM-DD, date will be padded to the end of the day. Similarly, if an endDate is specified, the response will include events with an end time earlier than 23:59 of the provided endDate.
status, string, optional, Published or Draft
access, string, optional, All Members, Selected Spaces Only, or Public
unlisted, boolean, optional, whether the event is unlisted

Response Example:

{
    "size": 2,
    "pageNumber": 1,
    "pageSize": 2,
    "results": [
        {
            "eventId": "654180e3566f8d5a7fb49e86",
            "eventTitle": "Q4 Engineering Summit",
            "eventType": "Livestream",
            "eventTimezone": "America/Los_Angeles",
            "eventStartTime": "2024-10-30T07:00:00.000Z",
            "eventEndTime": "2024-10-30T09:00:00.000Z",
            "eventCreatedTime": "2024-10-15T22:34:11.099Z",
            "eventCreatedFrom": "CommunityDashboard",
            "eventSlug": "q4-engineering-summit-2024-10-30",
            "eventUrl": "https://test.gradual/home/events/q4-engineering-summit-2024-10-30",
            "eventStatus": "Published",
            "eventCoverUrl": "https://abc.cloudfront.net/uploads/test/cover-12345.png",
            "eventTag": [
                "Engineering",
                "Quarterly"
            ],
            "eventLocation": "",
            "access": "Public",
            "spaces": [],
            "unlisted": false
        },
        {
            "eventId": "64adee61dc5dfe85abf9ae3e",
            "eventTitle": "Bay Area Networking Mixer",
            "eventType": "In-Person",
            "eventTimezone": "America/Los_Angeles",
            "eventStartTime": "2024-11-15T18:00:00.000Z",
            "eventEndTime": "2024-11-15T21:00:00.000Z",
            "eventCreatedTime": "2024-10-20T14:05:53.487Z",
            "eventCreatedFrom": "CommunityDashboard",
            "eventSlug": "bay-area-networking-mixer-2024-11-15",
            "eventUrl": "https://test.gradual/home/events/bay-area-networking-mixer-2024-11-15",
            "eventStatus": "Published",
            "eventCoverUrl": "https://abc.cloudfront.net/uploads/test/cover-67890.png",
            "eventTag": [
                "Networking"
            ],
            "eventLocation": "San Francisco, CA",
            "access": "Selected Spaces Only",
            "spaces": [
                "Space 1",
                "Space 2"
            ],
            "unlisted": false
        }
    ]
}

Get an Event by Event ID

URL: https://api.gradual-api.com/public-api/v1/events/:eventId

HTTP Method: GET

Content type: application/json

Tier: Light

Path Parameters:

eventId, string, required, this is the unique identifier to find an event

Response Example:

{
    "eventId": "654180e3566f8d5a7fb49e86",
    "eventTitle": "Q4 Engineering Summit",
    "eventType": "Livestream",
    "eventTimezone": "America/Los_Angeles",
    "eventStartTime": "2024-10-30T07:00:00.000Z",
    "eventEndTime": "2024-10-30T09:00:00.000Z",
    "eventCreatedTime": "2024-10-15T22:34:11.099Z",
    "eventCreatedFrom": "CommunityDashboard",
    "eventSlug": "q4-engineering-summit-2024-10-30",
    "eventUrl": "https://test.gradual/home/events/q4-engineering-summit-2024-10-30",
    "eventStatus": "Published",
    "eventCoverUrl": "https://abc.cloudfront.net/uploads/test/cover-12345.png",
    "eventTag": [
        "Engineering",
        "Quarterly"
    ],
    "eventLocation": "",
    "access": "All Members",
    "spaces": [],
    "unlisted": false
}

Get Event Attendees

URL: https://api.gradual-api.com/public-api/v1/events/:eventId/attendees

HTTP Method: GET

Content type: application/json

Tier: Medium

Path Parameters:

eventId, string, required, this is the unique identifier to find an event

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50
userEmail, string, optional, filter attendees by their email address. Special characters must be URL-encoded — for example [email protected] must be sent as user%[email protected]. Unencoded + is decoded as space by the URL parser and will be rejected with a 400 invalid email error.
userId, string, optional, filter attendees by their user ID

Response Example:

{
    "size": 2,
    "pageNumber": 1,
    "pageSize": 2,
    "results": [
        {
            "attendeeId": "654d66f8ea532ea2ac8cf004",
            "userId": "654d6623ea532ea2ac8ced28",
            "attendeeFirstName": "Jane",
            "attendeeLastName": "Doe",
            "attendeeDisplayName": "Jane Doe",
            "attendeeEmail": "[email protected]",
            "attendeeType": "Attendee",
            "ticketType": "General Admission",
            "registeredAt": "2023-11-09T23:10:48.118Z",
            "attendeeLinkedUrl": "https://www.linkedin.com/in/janedoe",
            "attendeeCompanyName": "Test Company",
            "attendeePosition": "Software Engineer",
            "eventQuestions": "What is your dietary preference?: Vegetarian;\nHow did you hear about this event?: LinkedIn, Newsletter;"
        },
        {
            "attendeeId": "65488c238314ce3add483d54",
            "userId": "64bffb03c4ac58e329f0f0b4",
            "attendeeFirstName": "John",
            "attendeeLastName": "Smith",
            "attendeeDisplayName": "John Smith",
            "attendeeEmail": "[email protected]",
            "attendeeType": "Speaker",
            "ticketType": "VIP",
            "registeredAt": "2023-11-06T06:48:03.354Z",
            "attendeeLinkedUrl": "",
            "attendeeCompanyName": "Gradual Inc",
            "attendeePosition": "Product Manager",
            "eventQuestions": ""
        }
    ]
}

Get Attendee by Attendee ID

URL: https://api.gradual-api.com/public-api/v1/events/:eventId/attendees/:attendeeId

HTTP Method: GET

Content type: application/json

Tier: Light

Path Parameters:

eventId, string, required, this is the unique identifier to find an event
attendeeId, string, required, this is the unique identifier to find an attendee

Response Example:

{
    "attendeeId": "654d66f8ea532ea2ac8cf004",
    "userId": "654d6623ea532ea2ac8ced28",
    "attendeeFirstName": "Jane",
    "attendeeLastName": "Doe",
    "attendeeDisplayName": "Jane Doe",
    "attendeeEmail": "[email protected]",
    "attendeeType": "Attendee",
    "ticketType": "General Admission",
    "registeredAt": "2023-11-09T23:10:48.118Z",
    "attendeeLinkedUrl": "https://www.linkedin.com/in/janedoe",
    "attendeeCompanyName": "Test Company",
    "attendeePosition": "Software Engineer",
    "eventQuestions": "What is your dietary preference?: Vegetarian;\nHow did you hear about this event?: LinkedIn, Newsletter;"
}

Register User to an Event

URL: https://api.gradual-api.com/public-api/v1/registration

HTTP Method: POST

Content type: application/json

Tier: Medium

Request Body Parameters:

eventSlug, string, required, slug of the event
email, string, required, user email
firstName, string, required, user first name
lastName, string, required, user last name
position, string, required, user job title
company, string, required, user company name
ticketOptionId, string, optional, id of ticket option (available from event dashboard)

Response Example (success, 200):

{
    "message": "Registration successful"
}

Response Example (user already registered, 400):

{
    "message": "User with email \"[email protected]\" already registered for this event."
}

Get Event Invitees

URL: https://api.gradual-api.com/public-api/v1/events/:eventId/invitees

HTTP Method: GET

Content type: application/json

Tier: Medium

Path Parameters:

eventId, string, required, this is the unique identifier of the event

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200
ticketType, string, optional, ticket name (e.g. "VIP Pass"). Must match an existing ticket on the event exactly; an unknown name returns a 400 error.
attendeeType, string, optional, one of "Attendee", "Speaker", "Host", "Staff", "Guest", "Press", "Sponsor". An unrecognized value returns a 400 error.
inviteeEmail, string, optional, filter invitees by their email address. Special characters must be URL-encoded — for example [email protected] must be sent as user%[email protected]. Unencoded + is decoded as space by the URL parser and will be rejected with a 400 invalid email error.
inviteAdminEmail, string, optional, filter invitees by the invite admin's email address. Must belong to a community member; an unknown email returns a 400 error. Note: the response field below is inviteAdmin and contains the admin's display name.

Response Example:

{
    "size": 2,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "inviteeId": "665a1b2c3d4e5f6a7b8c9d0e",
            "inviteeEmail": "[email protected]",
            "attendeeType": "Attendee",
            "ticketType": "VIP Pass",
            "inviteAdmin": "Sarah Chen",
            "ccEmailAddresses": ["[email protected]"],
            "note": "Key account - priority",
            "createdAt": "2026-04-10T14:30:00.000Z",
            "usedAt": "2026-04-12T09:15:22.000Z",
            "usedBy": {
                "userId": "6553ce608b3f645e79d95034",
                "displayName": "Jane Doe"
            }
        },
        {
            "inviteeId": "665a1b2c3d4e5f6a7b8c9d0f",
            "inviteeEmail": "[email protected]",
            "attendeeType": "Speaker",
            "ticketType": "VIP Pass",
            "inviteAdmin": null,
            "ccEmailAddresses": [],
            "note": "",
            "createdAt": "2026-04-10T14:35:00.000Z",
            "usedAt": null,
            "usedBy": null
        }
    ]
}

Field notes:

Only email-based invitations are returned. Code-based invitations (reusable codes shared across multiple redemptions) are not included.
inviteAdmin is the display name of the invite admin user when one is assigned, otherwise null.
ccEmailAddresses is the list of emails of community members CC'd on the invitation. Order matches the order they were added.
usedAt and usedBy are populated once the invitee has redeemed the invitation by registering for the event. Both are null until the invite is redeemed.

Response Example (event not found, 404):

{
    "message": "Event not found."
}

Add an Invitee

URL: https://api.gradual-api.com/public-api/v1/events/:eventId/invitees

HTTP Method: POST

Content type: application/json

Tier: Medium

Path Parameters:

eventId, string, required, this is the unique identifier of the event

Request Body Parameters:

inviteeEmail, string, required, the email address to invite
ticketType, string, required, ticket name (e.g. "VIP Pass"). Must match an existing ticket on the event and be marked invitation-only.
attendeeType, string, required, one of "Attendee", "Speaker", "Host", "Staff", "Guest", "Press", "Sponsor"
note, string, optional, free-form note on the invitation, max 200 characters
inviteAdminEmail, string, optional, email address of the invite admin responsible for this invitation. Must belong to a community member who has Event Invite Admin permission on this event.
ccEmailAddresses, array of strings, optional, list of community member emails to CC on the invitation notification. Each email must belong to an existing community member.

Sending the invitation triggers the existing invitation email to the invitee.

Response Example (success, 200):

{
    "message": "Invitee added successfully"
}

Response Example (already invited for this ticket type, 400):

{
    "message": "User with email \"[email protected]\" is already invited for ticket type \"VIP Pass\"."
}

Response Example (already registered, 400):

{
    "message": "User with email \"[email protected]\" is already registered for this event."
}

Response Example (ticket type is not invitation-only, 400):

{
    "message": "Ticket type \"General Admission\" is not an invitation-only ticket type."
}

Response Example (ticket type not found, 400):

{
    "message": "Ticket type \"VIP Pass\" not found for this event."
}

Response Example (CC email is not a community member, 400):

{
    "message": "CC email \"[email protected]\" is not a community member."
}

Response Example (event not found, 404):

{
    "message": "Event not found."
}

Users

Courses