Use the Heylo API

Read your group's events, attendance, and roles from your own systems, and keep role membership and removals in sync automatically.

The API is included on the Business plan. See plans.

The Heylo API lets your own systems read your group's events, event attendance, and roles, and keep role membership in sync without an admin doing it by hand. It is built for groups that use multiple tools, and the API provides a seamless integration across all of them. Every request is made with an API key that the Heylo team issues for your group, or for every group in your organization on the Organization plan.

Get an API key

Contact the Heylo team to get a key. The team sends the key along with the IDs of the groups it covers. To rotate or delete a key, contact the team.

A key issued for one group works only for that group. A key issued for an organization works for every group in the organization, including groups added later.

Send a request

Every request carries your key in the Authorization header. Requests are a POST with a JSON body and a Content-Type: application/json header, and the type field in the body picks the operation. Send requests to the exact URLs below: a URL with a trailing slash is redirected and the request body is lost. There are three endpoints:

https://api.heylo.com/apiv1-fetch reads events, attendance, roles, and role members.
https://api.heylo.com/apiv1-update adds and removes role members.
https://api.heylo.com/apiv1-remove removes a member from a group.

This request fetches a group's events for January 2027. Replace HEYLO_API_KEY and HEYLO_GROUP_ID with your own values.

bash

curl -X POST https://api.heylo.com/apiv1-fetch \
  -H "Authorization: Bearer HEYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "HEYLO_GROUP_ID",
    "endTimestamp": 1801439999000,
    "startTimestamp": 1798761600000,
    "type": "communityEvents"
  }'

All timestamps are Unix time in milliseconds.

Rate limit

Each API key can make 5 requests per second, counted across all endpoints together. A request over the limit returns HTTP 429 with a Retry-After: 1 header, so wait a second and send it again. Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers, which you can use to pace a batch job.

Errors

A failed request returns an HTTP status and, in most cases, a JSON body with an errorMessage, such as {"errorMessage": "missing communityId"}. Two cases return plain text instead: a type the endpoint does not support (unsupported type parameter), and the 400 and 403 errors from the member removal endpoint.

400: a required field is missing, a limit was exceeded, or type is not one the endpoint supports.
401: the Authorization header is missing or is not in the form Bearer HEYLO_API_KEY.
403: the key is not valid, the key does not cover this group, or the event belongs to a different group.
404: the event or role does not exist.
429: the key went over the rate limit.
500: something failed on Heylo's side. Retry the request after a short wait.

Fetch events

Returns a group's events, sorted by start time, oldest first. The response includes role-restricted private events, canceled events (marked "canceled": true), and events another group created and shared with yours. Draft events are not included. Each event's communityId is the group that created it.

Endpoint: apiv1-fetch
type: "communityEvents"
communityId: the group ID
startTimestamp: return events that start at or after this time
endTimestamp: return events that start at or before this time
batchSize (optional): the number of events to return, 50 by default and 100 at most
lastEventId (optional): the ID of the last event from the previous page

Response: {"events": [...]}. Each event carries its eventId, its start time in timestamp, and its end time in timestampEnd.

Always send both startTimestamp and endTimestamp. The response is then the earliest events in that window, up to batchSize. A request with only one of the two, or neither, reads from a short list of recent and upcoming events and can leave out events you asked for.

To get the next page, repeat the request with the same endTimestamp, with startTimestamp set to the timestamp of the last event you received, and with lastEventId set to that event's eventId. Several events can start at the same moment, so a page can repeat an event from the previous one: keep events by eventId and skip ones you already have. You have reached the last page when a response holds fewer events than batchSize.

Fetch event attendance

Returns every attendance record for one event, including RSVPs, check-ins, guests, and registration answers.

Endpoint: apiv1-fetch
type: "eventAttendance"
communityId: the ID of the group that created the event, which is the event's communityId. For an event another group shared with yours, your key must also cover that group.
eventId: the event ID, from a fetch events response

Response: {"attendance": {...}}, an object keyed by Heylo user ID. Each record includes fullName, going (such as "yes", "maybe", or "no"), and checkedIn. On an event with a waitlist, members on the waitlist also have going set to "yes", so "yes" is not a confirmed spot. Registration answers are keyed by question ID.

Remove a member

Removes a member from a group and cancels any pending invite for the same person. Removal identifies the person by the ID they have in your own system, not by their Heylo user ID.

Removal only finds members whose ID from your system was attached when the Heylo team imported them. Members who joined any other way cannot be removed through the API.

Endpoint: apiv1-remove
type: "member"
communityId: the group ID
userId: the member's ID in your system

bash

curl -X POST https://api.heylo.com/apiv1-remove \
  -H "Authorization: Bearer HEYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "HEYLO_GROUP_ID",
    "type": "member",
    "userId": "YOUR_MEMBER_ID"
  }'

Response: the text ok. The response is the same when no member or invite matched the ID, so a repeated removal is safe.

Fetch roles

Returns every role in a group.

Endpoint: apiv1-fetch
type: "communityRoles"
communityId: the group ID

Response: {"roles": [...]}. Each role includes its id, name, and description.

Fetch role members

Returns the members who hold one role.

Endpoint: apiv1-fetch
type: "roleMembers"
communityId: the group ID
roleId: the role's id, from a fetch roles response

Response: {"memberUserIds": [...]}, a list of Heylo user IDs.

Update role members

Adds and removes members from a role in one request. Role members are identified by Heylo user ID, the same IDs that key an attendance response and fill a role members response.

Endpoint: apiv1-update
type: "roleMembers"
communityId: the group ID
roleId: the role's id
addedUserIds (optional): Heylo user IDs to give the role, up to 100 per request
removedUserIds (optional): Heylo user IDs to take the role from, up to 100 per request

Send at least one of addedUserIds or removedUserIds. IDs that do not belong to a current member of the group are skipped without an error. An ID in both lists is removed from the role.

Response: {"addedUserIds": [...], "removedUserIds": [...]}, the IDs that were applied. An ID missing from the response was skipped because it is not a current member. A member who already had the role, or never had it, still appears in the response.