API

This guide explains how to automate adding and removing members in Heylo via our REST‑only API.

TL;DR – It’s two HTTPS endpoints, both POST, authenticated with a single bearer token. You create invites or remove members with simple JSON payloads. No sessions, no WebSockets, no surprises.

1. Prerequisites

2. Authentication

Every request must include the bearer token header:

Authorization: Bearer HEYLO_API_KEY
Content‑Type: application/json

Need to rotate? Contact us or email [email protected] and we’ll issue a new one.

3. Rate limits

• Soft limit: up to 5 concurrent requests per organization.

• Best practice: Send one request at a time, wait for the 2xx response, then send the next.

• No hard per‑minute cap (yet). We’ll introduce structured 429s once the surface expands.

4. Endpoints

Coming soon: Update and fetch endpoints so you can edit member data or retrieve roster snapshots.

5. Request format

5.1 Create Invite

{
  "communityId": "abc123",             // required – Heylo group ID
  "member": {
    "userId": "user‑42",               // stable ID in *your* system
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "[email protected]",
    "phoneNumber": "+1‑555‑867‑5309",
    "birthDate": "1815‑12‑10",
    "gender": "female",               // male | female | non-binary | decline
    "memberSinceMonth": "May",
    "memberSinceYear": "2024",
    "emergencyContactName": "Charles Babbage",
    "emergencyContactPhoneNumber": "+1‑555‑123‑4567",
    "emergencyContactRelationship": "Friend"
  },
  "replyToEmail": "[email protected]", // optional – override default reply‑to
  "suppressEmails": false,                // true = skip Heylo invite/reminder emails
  "type": "invite"                       // *always* "invite" for this endpoint
}

Example cURL

curl -X POST \
  https://us-central1-piccup-82257.cloudfunctions.net/apiv1-create \
  -H "Authorization: Bearer HEYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @invite.json

5.2 Remove Member

{
  "communityId": "abc123",  // Heylo group ID
  "userId": "user‑42",      // same stable ID you used to create the invite
  "type": "member"          // *always* "member" for this endpoint
}

Removing a member automatically cancels any pending invites for the same [userId, communityId] pair.

Example cURL

curl -X POST \
  https://us-central1-piccup-82257.cloudfunctions.net/apiv1-remove \
  -H "Authorization: Bearer HEYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"communityId":"abc123","userId":"user-42","type":"member"}'

Need help? No problem! Contact the Heylo team or email us at [email protected].