> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtuous.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> An orientation to the Volunteer API — what VOMO is, what the API exposes, what makes it distinct from the other Virtuous APIs, and what partner integrations typically use it for.

The Volunteer API (commonly referred to internally as the **VOMO API**) gives partner integrations programmatic access to a customer's volunteer management data in VOMO — their Users, Projects, Groups, Campaigns, Organizations, Forms, and Certificates. It's the third of the three Virtuous APIs, alongside [CRM+](/crm/overview) and [Raise](/raise/overview), and it's the most distinct of the three in conventions, scope, and design.

This page covers what the API is for, how it differs from the other two Virtuous APIs, and what partner integrations typically build against it.

## What VOMO is

VOMO is Virtuous's volunteer engagement platform. Customers use it to:

* Recruit and manage volunteer **Users**
* Plan and run **Projects** (specific volunteer opportunities)
* Organize **Groups** of volunteers around recurring activities or affinities
* Track **Participations** when volunteers show up to Project Dates
* Group Projects under longer-running **Campaigns**
* Manage **Forms** that volunteers complete (waivers, signups, profile data)
* Award **Certificates** for completed training or achievements
* Operate as part of an **Organization** family (parent-child organization hierarchies)

The API exposes these resources for read access (heavy) and a limited surface of write operations.

## At a glance

| Aspect                | Value                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------- |
| **Base URL**          | `https://api.vomo.org/v1`                                                                 |
| **Authentication**    | Bearer token (issued via VOMO admin portal)                                               |
| **Resource families** | 8 (Users, Groups, Projects, Project Dates, Campaigns, Organizations, Forms, Certificates) |
| **Total endpoints**   | 24                                                                                        |
| **Pagination**        | Page-based with `data`/`links`/`meta` envelope                                            |
| **Property naming**   | `snake_case`                                                                              |
| **Webhooks**          | Not available — polling only                                                              |
| **Versioning**        | URL segment (`/v1/`)                                                                      |
| **Read vs. write**    | Heavily read-oriented; limited writes on Users, Groups, Projects                          |

## How Volunteer differs from CRM+ and Raise

If you've worked with CRM+ or Raise, several Volunteer conventions will look different. Understanding the differences upfront prevents bugs.

### Naming conventions are snake\_case

Volunteer uses `snake_case` everywhere — query parameters (`name_like`, `created_before`, `updated_after`) and response properties (`first_name`, `last_name`, `created_at`, `user_status`). This is consistent throughout the API but **differs from CRM+ (PascalCase) and Raise (mixed PascalCase on `/list`, camelCase on `/query`)**.

For partners building integrations against multiple Virtuous APIs:

```javascript JavaScript theme={null}
// CRM+ — PascalCase parameters
const crmGifts = await fetch('https://api.virtuoussoftware.com/api/Gift/Query', {
  method: 'POST',
  body: JSON.stringify({ Skip: 0, Take: 100, SortBy: 'CreatedDateTime' }),
});

// Raise — mixed casing
const raiseGifts = await fetch('https://prod-api.raisedonors.com/api/Gift/list?Take=100&SortBy=date');

// Volunteer — snake_case
const vomoUsers = await fetch('https://api.vomo.org/v1/users?name_like=smith&created_after=2025-01-01');
```

Each API is internally consistent; the inconsistency is across APIs. See [Conventions across the three APIs](#conventions-across-the-three-apis) below.

### Pagination uses a different envelope

CRM+ and Raise use `{ list, total }` and `{ items, total }` envelopes respectively. Volunteer uses a richer Laravel-style envelope with three top-level fields:

```json theme={null}
{
  "data": [ /* array of resource objects */ ],
  "links": {
    "first": "https://api.vomo.org/v1/users?page=1",
    "last": "https://api.vomo.org/v1/users?page=8",
    "prev": null,
    "next": "https://api.vomo.org/v1/users?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 15,
    "per_page": 15,
    "last_page": 8,
    "total": 120
  }
}
```

The `links` field provides direct URLs for paging navigation — partners can follow `links.next` rather than constructing URLs manually. See [Pagination](/volunteer/pagination) for the full pattern.

### No webhooks — polling is the only path

Unlike CRM+ and Raise (which both have webhook subscription APIs), Volunteer has no webhook surface at all. Partner integrations that need to react to changes in Volunteer data must poll — typically by querying with the `updated_after` filter on resources that support it.

This shapes the integration architecture significantly. The "Webhooks and Events" group in the CRM+ and Raise docs is replaced by [Polling and Sync](/volunteer/polling-and-sync/overview) in the Volunteer docs.

### Mostly read, limited writes

The API is dominated by `GET` endpoints. The write endpoints that do exist:

| Resource | Write operations                                                                      |
| -------- | ------------------------------------------------------------------------------------- |
| Users    | `POST /users` (create or update — upsert behavior)                                    |
| Groups   | `POST /groups`, `PUT /groups/{id}`, `DELETE /groups/{id}`, `PUT /groups/{id}/members` |
| Projects | `POST /projects`, `PUT /projects/{id}`                                                |

Most notably, **there's no write endpoint for Participations.** Partners can read participation records (returned nested on User and Project Date responses) but cannot create or modify them through the API. Partners who need to record participations programmatically must coordinate with VOMO's admin team for an alternative path.

See [Understand Write Limitations](/volunteer/workflows/understand-write-limitations) for the complete picture.

### URL-versioned

Volunteer's path includes a `/v1/` segment: `https://api.vomo.org/v1/users`. This is different from Raise (which is unversioned) and CRM+ (which uses unversioned `/api/` paths). The presence of `/v1/` suggests a future `/v2/` may exist someday and existing integrations would have a migration path.

For now, all integrations use `/v1/`. See [Versioning and Backward Compatibility](/volunteer/best-practices/versioning-and-backward-compatibility).

***

## The resource model

The eight resource families and how they relate:

```mermaid theme={null}
graph TD
  Org["Organization<br/>(parent-child hierarchy)"]
  User["User<br/>(volunteer)"]
  Project["Project<br/>(volunteer opportunity)"]
  ProjectDate["Project Date<br/>(specific occurrence)"]
  Participation["Participation<br/>(volunteer's attendance)"]
  Group["Group<br/>(volunteer grouping)"]
  Campaign["Campaign<br/>(initiative spanning Projects)"]
  Form["Form<br/>(data-collection form)"]
  Certificate["Certificate<br/>(training / achievement)"]

  Org -->|owns| Project
  Org -->|owns| Group
  Org -->|owns| Campaign
  Org -->|child orgs| Org
  Campaign -->|contains| Project
  Project -->|scheduled at| ProjectDate
  ProjectDate -->|has| Participation
  User -->|recorded in| Participation
  User -->|belongs to| Group
  User -->|earns| Certificate
  User -->|completes| Form
  Project -->|attaches| Form
```

The central relationships:

| Relationship                           | Meaning                                                                             |
| -------------------------------------- | ----------------------------------------------------------------------------------- |
| **User ↔ Participation ↔ ProjectDate** | Volunteers attend specific occurrences of Projects, producing Participation records |
| **Project ↔ ProjectDate**              | A Project is the volunteer opportunity; each scheduled occurrence is a ProjectDate  |
| **Campaign ↔ Project**                 | Campaigns group related Projects under a longer-running initiative                  |
| **Organization ↔ Org**                 | Organizations can have parent-child relationships ("organization family")           |
| **User ↔ Group**                       | Volunteers can belong to one or more Groups                                         |
| **User ↔ Form**                        | Volunteers complete Forms (waivers, profile data, signups)                          |
| **User ↔ Certificate**                 | Volunteers earn Certificates for completed training or activities                   |

See [The Volunteer Data Model](/volunteer/concepts/data-model) for the full reference.

***

## What partner integrations build against the Volunteer API

Common partner integration patterns:

| Integration type                        | What it does                                                                                |
| --------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Reporting and BI**                    | Pulls volunteer engagement metrics into dashboards, BI tools, or data warehouses            |
| **Donor-volunteer crossover analytics** | Identifies donors who also volunteer (and vice versa) by syncing with CRM+                  |
| **External CRM sync**                   | Mirrors Volunteer's User and Participation data into a generic CRM for unified stewardship  |
| **Communications platforms**            | Uses Volunteer data to segment volunteers by activity for email or SMS outreach             |
| **Compliance and certifications**       | Tracks training completion via Certificates for organizations with regulated programs       |
| **Custom reporting**                    | Builds organization-specific reports (volunteer hours per Project, retention metrics, etc.) |

Most of these are read-heavy. Volunteer's API surface is well-suited to feeding data outward into other systems.

What the API is **not** typically used for:

* **Recording new participations** — no write endpoint exists
* **Managing volunteer scheduling** — Project Dates are read-only; scheduling happens in the VOMO admin UI
* **Volunteer self-service** — the API isn't designed for direct exposure to volunteers; build a partner-controlled portal layer instead
* **Webhook-driven real-time sync** — no webhooks exist

***

## Conventions across the three Virtuous APIs

A quick reference for partners building against multiple APIs:

| Convention              | CRM+                               | Raise                                        | Volunteer                     |
| ----------------------- | ---------------------------------- | -------------------------------------------- | ----------------------------- |
| **Base URL**            | `https://api.virtuoussoftware.com` | `https://prod-api.raisedonors.com`           | `https://api.vomo.org/v1`     |
| **Versioning**          | No `/v1/` segment                  | No `/v1/` segment                            | `/v1/` segment in URL         |
| **Auth**                | Bearer JWT                         | Bearer JWT                                   | Bearer JWT                    |
| **Param casing**        | PascalCase                         | PascalCase on `/list`, camelCase on `/query` | snake\_case                   |
| **Property casing**     | PascalCase                         | camelCase                                    | snake\_case                   |
| **Pagination envelope** | `{ list, total }`                  | `{ items, total }`                           | `{ data, links, meta }`       |
| **Pagination model**    | `Skip` / `Take` offsets            | `skip` / `take` offsets                      | `page` numbers                |
| **Webhooks**            | Yes (8 endpoints)                  | Yes (8 endpoints)                            | None                          |
| **Write endpoints**     | Many                               | Many                                         | Few (Users, Groups, Projects) |

The three APIs were built by different teams at different times (some pre-acquisition by Virtuous). The differences reflect those histories. The v2 platform overhaul is expected to reconcile many of these inconsistencies, but until then, integrations target each API on its own terms.

***

## What's documented here

The Volunteer documentation covers:

| Group                   | What it covers                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Get Started**         | This page, plus authentication, base URLs, first API call, error handling, pagination, rate limits           |
| **Core Concepts**       | The resource model, each resource family, how to think about Participations, the organization hierarchy      |
| **Common Workflows**    | The everyday tasks — listing users, creating groups, updating projects, working around the write limitations |
| **Polling and Sync**    | The patterns for change detection without webhooks                                                           |
| **Integration Recipes** | End-to-end recipes for common partner integration scenarios                                                  |
| **Best Practices**      | Performance, security, error recovery, versioning, sync architecture                                         |

Notably **absent** (compared to CRM+ and Raise):

* **No "Webhooks" group** — replaced by Polling and Sync, since Volunteer has no webhook surface.
* **Fewer recipes** — the smaller API surface produces fewer distinct integration shapes.

***

## What's in the spec but flagged for review

The Volunteer OpenAPI spec has several gaps the documentation team is aware of and that partner integrations should know about:

| Gap                                                | Implication                                                                                                                                |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **17 of 20 endpoints document no error responses** | The spec says nothing about `401`, `403`, `404`, or `500`. Defensive coding is essential.                                                  |
| **Empty `schema: {}` on several endpoints**        | The Organization endpoints, several Campaign endpoints, and others have no formal response shape — only inline examples.                   |
| **Schema description copy-paste errors**           | `CampaignResource` says "A VOMO Project"; `ParticipationResource` says "List of Groups"; others have similar issues.                       |
| **`hours` field type mismatch**                    | Typed as `integer` in spec but returns fractional values (e.g., `4.00`) from the live API. Code should expect a number, not an integer.    |
| **Resource naming inconsistency**                  | The same resource appears as "certificate", "certification", and "certifications" in different places. Live API uses `/certificates` path. |
| **Placeholder field descriptions**                 | `PUT /projects/{id}` has many fields with `"Update Project"` as the description (placeholder text left in).                                |
| **PATCH not supported**                            | Updates require full-record `PUT`. No partial-update support.                                                                              |

These are documented inline on the relevant reference pages with `<Warning>` callouts. Until the spec is updated, the patterns on this page describe what to expect from the live API.

***

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/volunteer/quickstart">
    A minimal end-to-end example — get a token, list users, parse the response.
  </Card>

  <Card title="Authentication" icon="key" href="/volunteer/authentication">
    How to obtain a Bearer token and use it on every request.
  </Card>

  <Card title="The Volunteer Data Model" icon="diagram-project" href="/volunteer/concepts/data-model">
    The full resource model with all eight families and their relationships.
  </Card>

  <Card title="Conventions across APIs" icon="layer-group" href="#conventions-across-the-three-virtuous-apis">
    The cross-API reference for partners building against multiple Virtuous products.
  </Card>
</CardGroup>