Start here: what the API is

Shoal's API is a way for another tool to talk to your events without anyone signing in. A spreadsheet can send Shoal a list of people to invite, or pull in everyone who has registered. A form tool can add each new person to your event as they sign up. You don't need to be a programmer: the guides in this section give you everything to copy and paste.

Words you'll see

1. API key: a long secret code that proves a request comes from your organization. It works like a password for tools. You create keys on the API page.
2. Event id: the long code that names one event, like 3f2b9c1e-7a4d-4b8e-9f10-2c6d5e8a1b23. The guide "Create a key and find your event id" shows where to find it.
3. URL (web address): where a tool sends its request. Every Shoal address starts with https://shoalevents.com/api/v1.
4. GET: a request that reads something, such as "list my attendees". It never changes anything.
5. POST: a request that adds or updates something, such as "add these people". PATCH changes one thing, like an event's name.
6. JSON: the text format requests and answers use. It looks like {"email": "pat@example.com", "first_name": "Pat"}: names in quotes, a colon, then the value.
7. Header: a hidden line sent with each request. Shoal needs one called Authorization that holds your key, written as Bearer followed by a space and the key.

What you can connect

1. Google Sheets: send a list of people to Shoal from a sheet, and pull registrations back into another sheet. No extra accounts needed.
2. Zapier or Make: add someone to your event every time something happens elsewhere, such as a new Google Form, Typeform or Jotform answer.
3. Airtable: send an Attendees table to Shoal with an automation.
4. Webhooks: have Shoal tell another tool the moment someone registers, joins the waitlist, cancels or checks in. See the Webhooks guide.
5. Anything else that can send a web request (most tools call this a "webhook" or "HTTP request" step).

Good to know

1. People are matched by email. Sending the same person twice updates them; it never makes a second copy.
2. The API never emails anyone. People you add are Invited (or Registered if you say so), and you send invitations and tickets from the Attendees screen when you're ready. Notifications you send through the API do appear in the attendee app and on phones that turned notifications on.
3. Empty values you leave out are never changed. Only the fields you send are updated.
4. If anything in a request is wrong, nothing from that request is saved, and the error says what to fix.
5. Beyond people, the API can also read and change your events, tracks, speakers, sessions, audiences, sponsors and sponsor tiers, notifications and custom pages. The API reference lists every address.

Next: Create a key and find your event id