Overview

The APIs & webhooks card in Integrations & Apps opens Vome's developer console. It is what you use when you want to build something custom, rather than use a ready-made connector.

There are two halves, and most projects use both.

• The API is you asking Vome for data, or sending data in. You make the call, Vome answers.

• Webhooks are Vome telling you the moment something happens, so your system does not have to keep checking.

APIs and webhooks are available on the Ultimate plan.

Why use them

• Push Vome data into systems we do not connect to directly. A data warehouse, a finance system, a custom intranet, an internal dashboard.

• Keep another system current without anyone re-typing anything. A webhook fires the second a profile is created or a shift is booked.

• Automate work that spans several tools. The same API key powers the Zapier and Microsoft Power Automate connectors, so you can start no-code and move to custom code later without changing credentials.

• Report on your own terms. Pull profiles, reservations, shifts and form submissions into whatever reporting tool your organization already uses.

Where you find it in Vome

From the left-hand navigation, click Integrations & Apps, then APIs & webhooks. This opens the developer console, which has four tabs:

• API keys, where you generate and revoke the secret keys that authenticate your requests.

• Webhooks, where you register the endpoints Vome should notify and choose which events they receive.

• Events, a record of the events Vome has produced on your account.

• Logs, where you check what Vome sent, what your endpoint returned, and why a delivery failed.

What the API can reach

The API is a REST API with JSON responses, served from https://api.vomevolunteer.com over HTTPS.

There are eight resources. Most offer the same three reads, which are to list them, retrieve one by its id, and search them with filters. Some also accept writes. Each entry below says exactly which calls exist, what the object actually contains, and what people typically build with it.

How the objects fit together

Most of these objects hang off a single hierarchy, so it is worth reading this before you pick an endpoint:

category → opportunity → shift → reservation

A category groups related work, for example Food Bank. An opportunity is a role or programme inside that category, for example Weekend Mentor. A shift is one dated block of time on that opportunity, for example Saturday 9am to 12pm with 8 spots. A reservation is one person booked into one shift. Categories have no endpoint of their own, they arrive nested inside the opportunity object.

Onboarding runs on a parallel pair. A sequence is the template, and a user sequence is one person's run through that template.

Profiles

One person's record in your database.

Two kinds exist and the API returns both. A Vome User has an account and signs in. An offline profile is one your organization maintains on someone's behalf, for a person who never logs in. The is_offline flag tells them apart.

A profile carries identity and contact data (name, email, phone, date of birth, gender, occupation, institution, skills, languages, address and coordinates), an emergency contact, optional medical information, lifetime logged_hours, a completed_shifts count, the opportunities the person is assigned to, the profile tags your administrators have applied, and any custom fields your organization has defined.

Reads: list, retrieve, search, plus a separate call that lists every profile field on your account. Writes: create, update and upsert.

Typically built with it: a nightly upsert from an HR or membership system, so a person who joins there appears in Vome without being typed in twice. Call the profile-fields endpoint first to discover your own custom field ids, since those are UUIDs specific to your account.

Opportunities

The role or programme that shifts belong to.

An opportunity is the thing a person signs up for. It holds the title, description, status, creation date, its parent category, and a public share URL once it is published. One opportunity usually has many shifts underneath it.

Reads: list, retrieve, search. Writes: assign users to opportunities.

Typically built with it: publishing your live opportunities on your own website from the share URL, rather than maintaining a second list by hand.

The path to a single opportunity is /api/opportunities/{opportunity_role_id}/. That parameter is named opportunity_role_id for historical reasons, but the value it wants is the opportunity's own id. Vome dropped the word "role" from its product language a while ago and the API path has not caught up.

Shifts

A single dated block of time people can be booked into.

A shift belongs to exactly one opportunity, and an opportunity can have many. It carries the title, description, start and end times, capacity, its parent opportunity, a derived location, and a public share URL. Capacity is what tells you whether the shift still has room.

Reads: list, retrieve, search. Writes: assign users to shifts.

Typically built with it: mirroring next week's shifts into a staff calendar or a signage board, or booking a person onto a shift from another system once they are approved there.

Reservations

One person's place on one shift.

If the shift is the slot, the reservation is the booking against it, so one shift holds many reservations, one per person. This is where attendance and hours actually live, which makes it the object most reporting integrations are really after.

It carries a status that moves through the full lifecycle (shift request pending, reserved, shift request declined, attendance confirmed, absent, checked in, hours logged, hour claim pending, cancelled), an arrival_time and departure_time, the resulting logged_hours, and who approved those hours (empty when a QR code check-out did it). It also nests the shift, the person and the opportunity, so a single reservation record answers who did what, when, and for how long.

Read only. List, retrieve, search.

Typically built with it: pulling last month's reservations that reached hours logged, and pushing the totals into a grant report, a finance system or a data warehouse.

Sequences

A reusable, ordered checklist of onboarding or screening steps.

A sequence is a template, not anyone's progress. It carries the title, description, status, visibility, and an ordered array of steps, where each step has a position, a type, and its own details. A step is the unit that stands for a requirement: a form to complete, a waiver to sign, a document to read, a training to finish, an interview to attend.

Reads: list, retrieve, search. Writes: assign users to sequences.

Typically built with it: reading your sequence structure once to build matching stages in your own tracker, then assigning a person to the right sequence automatically when they clear a step somewhere else.

User sequences

One person's progress through one sequence.

Assigning someone to a sequence creates a user sequence, and this is the object to read for progress. The enrollment itself has a status of Active, Paused, Inactive or Finished, plus timestamps for when the person joined and when anything last changed.

Inside it, every step reports its own state: Added or Completed, the date it was completed, an expiration date where one applies, and whether a file was uploaded against it. That per-step detail is what lets you answer "is this person cleared to work yet", rather than only "have they started".

Read only. List, retrieve, search.

Typically built with it: holding back scheduling in your own system until a person's screening sequence reports Finished, or chasing the one step still outstanding.

Form submissions

One completed response to one of your forms.

A submission is created when someone submits a form you built in Vome, and it captures much more than the answers. Alongside the form's id and title, the folder it sits in, the submission timestamp and a submission_status (New, In Review, Reviewed, Rejected or Completed), it holds the full questions array: each question asked, the person's answer, the answer type, and whether they responded at all.

It also carries what the form collected around the answers. That includes medical information and emergency contact, digital consent and how it was given (typed, uploaded, or not provided), general availability by day and time of day, file attachments, the opportunity the person arrived from, any shifts they requested, and the sites and categories tied to the submission.

Read only. List, retrieve, search.

Typically built with it: routing each new application into a CRM or an approval workflow the moment it lands, with the consent record and attachments carried across.

Sites

One location or branch inside a multi-site organization.

A site is a place under your organization's umbrella. Most organizations use it for a branch, a campus, a chapter or a region. Each one carries a name, description, address, general email, general phone and website. People relate to sites by membership, and the API manages that membership directly.

Reads: list, retrieve. There is no search endpoint for sites. Writes: create sites in bulk, assign people to sites, and remove people from sites.

Typically built with it: creating your whole branch list in one call during setup, then keeping site membership in step with your identity provider or HR system as people move between locations.

Which events webhooks can send

When you create a webhook endpoint, you choose which events it should receive. Events are grouped into four families:

• Profiles

• Bookings

• Form submissions

• Sequences

You can subscribe one endpoint to several families, or run separate endpoints for separate purposes.

How to generate an API key

1. From the left-hand navigation, click Integrations & Apps.

2. Click APIs & webhooks.

3. Open the API keys tab and click Generate secret key.

4. Give the key a descriptive title, so you can tell later which system is using it.

5. Copy the key and store it somewhere safe.

The key is shown once. If you lose it, you cannot look it up again, you generate a new one and update whatever was using the old key. Never paste a key into client-side code or a public repository.

Send the key on every request in the API-KEY header.

How to create a webhook endpoint

1. In the developer console, open the Webhooks tab.

2. Click to create a webhook endpoint.

3. Enter the endpoint URL. It has to be a live URL that can accept the request, not a placeholder you plan to build later.

4. Add a short description, so the purpose of the endpoint is obvious to whoever looks at it next.

5. Select the events you want delivered, from the Profiles, Bookings, Form submissions and Sequences groups.

6. Save the endpoint.

Once it is live, use the Logs tab to confirm deliveries are succeeding. A failed delivery there tells you whether the problem is on Vome's side or your endpoint's.

Developer documentation

The full technical reference lives on Vome's developer documentation site, separate from this help centre. Start here:

• Introduction and quickstart: https://docs.vomevolunteer.com/getting-started/quickstart

• Authentication: https://docs.vomevolunteer.com/getting-started/publish-your-docs

• Errors: https://docs.vomevolunteer.com/getting-started/errors

• Pagination: https://docs.vomevolunteer.com/getting-started/pagination

Every resource has its own object reference and endpoint list on the same site, and the connector guides for Zapier, Microsoft Power Automate and Salesforce sit under Integrations and Automations: https://docs.vomevolunteer.com

Need help?

If you are stuck on a request or a webhook delivery, contact our support team through https://support.vomevolunteer.com/. Include the endpoint you are calling and, where you can, the entry from the Logs tab.

Summary

• APIs and webhooks are on the Ultimate plan, under Integrations & Apps.

• Eight resources are reachable: profiles, opportunities, shifts, reservations, sequences, user sequences, form submissions and sites.

• Reads are available on all eight. Writes cover creating and updating profiles, creating sites, and assigning people to opportunities, shifts, sequences and sites.

• Reservations, user sequences and form submissions are read only, and they are where attendance, screening progress and application answers live.

• Webhooks push Profiles, Bookings, Form submissions and Sequences events to a URL you own.

• Generate the key in the API keys tab, copy it immediately, and send it in the API-KEY header.

• The Logs tab is where you diagnose a webhook that is not arriving.

• The full reference is at docs.vomevolunteer.com.