Skip to main content
An Organization in the Volunteer API represents a customer entity — typically a nonprofit, a corporation’s CSR program, or a similar group running a volunteer initiative. Organizations can be arranged in parent-child hierarchies — a national umbrella organization with regional chapter children, a corporation with departmental sub-orgs, an interfaith network with member organizations. This is the organization family concept that determines what data an API token can access: a token issued for a parent organization typically grants access to that organization and its children.

The two endpoints

Both are read-only. Organization records are managed in the VOMO admin UI; there’s no API path for creating, updating, or deleting Organizations.
⚠️ Spec gap (audit #25, #26, #27): The Organization endpoints have empty schema: {} in the OpenAPI spec — the response shape is documented only through inline examples. There is no OrganizationResource component schema.The fields documented on this page come from the spec’s inline examples and live API observations. Treat them as the working contract, but confirm against actual responses for production-critical workflows.

The Organization resource

Based on the spec’s inline example, an Organization has these fields:

Core identity

Contact information

Organizational metadata

Custom monikers

VOMO Organizations support custom display labels that override the default UI vocabulary: For partner integrations building user-facing displays, honor these monikers when displaying Organization-specific content. A customer that calls Projects “Events” appreciates seeing “Events” in your UI rather than “Projects.”

Address

The address field is an object with detailed location info:
The format follows the Google Places API convention. The formatted_address field is the human-readable string suitable for display. The logo field is a media object:
The urls object provides multiple sizes (s = small, o = original, l = large) for different display contexts.

Parent and child relationships

The defining fields for the organization family: Each entry in these arrays is itself an Organization-shaped object (potentially abbreviated), allowing the partner integration to navigate the hierarchy from any starting point.

The organization family pattern

The parent-child relationships form a tree (or in some cases, a more complex DAG):

What this enables

Resource attribution

Most resources in the API include organization attribution: For partner integrations doing per-org reporting or routing:
JavaScript
The org_slug query parameter on Project and Campaign endpoints accepts comma-separated values for multi-org queries.

Listing organizations

cURL
⚠️ Spec gap (audit #25): The GET /organizations endpoint’s summary describes returning “organizations in your organizations family,” but the spec’s example shows a single Organization object — not an array of Organizations. The pagination semantics aren’t clearly documented.Confirm against the live API whether this endpoint returns a single Organization (the parent), a paginated list of the family, or something else. The patterns below assume it returns the family hierarchy in some form.
For partner integrations that need to know the full organization family their token can access, this is the entry point.
JavaScript
If the response shape is “the parent Organization with its children listed,” walk the child_organizations array. If it’s “a list of organizations the token can access,” paginate the result.

Fetching a single organization

cURL
Returns the Organization with full detail, including its parent and child organization arrays.
JavaScript
Useful when you have a specific Organization ID (from a Project’s organization_id, from a previous family fetch, etc.) and need the full record.

Common workflows

Map child organizations for routing

For partner integrations that route data based on which org within the family it belongs to:
JavaScript
The slug-based lookup makes routing on project.organization_slug straightforward.

Display Organization monikers consistently

For UIs that display Organization-specific content:
JavaScript
A customer that calls their Projects “Events” gets to see “Events” everywhere in your integration.

Aggregate across the family vs. filter to one org

For reporting integrations:
JavaScript
The org_slug parameter on Project and Campaign endpoints is the canonical way to filter — comma-separated lists are supported.

Detect the token’s “home” organization

The Organization the API token was issued for is typically the parent. To detect it programmatically:
JavaScript
Useful for displaying “you’re integrated with [Home Org Name]” in your partner UI.

ID, slug, and the family

A few practical points about Organization identifiers: The slug is human-readable and stable across the Organization’s lifetime; the ID is the numeric primary key. Both are stable, but slugs are easier for humans to work with (and easier to communicate via documentation or settings UIs).

Filtering across multiple orgs

The org_slug query parameter on Project and Campaign endpoints accepts comma-separated values:
This returns Projects belonging to either of the two child organizations. Useful for partner integrations whose customer wants a subset of their family included in a specific workflow.

What this means for multi-org customers

Partner integrations serving customers with parent-child organization structures should: The integration’s design should accommodate single-org customers (most common) without making things complex, while also being able to handle multi-org families when they appear.

A reference Organizations client

Given the spec gaps around the Organization shape, the reference client treats fields defensively:
JavaScript
The ?? null and ?? defaults throughout reflect the spec gap reality — fields may be missing or have unexpected shapes, and the parser handles both gracefully.

Where to go next

Campaigns

The Campaign resource — Campaigns are owned by specific organizations within the family.

Groups

Groups belong to specific organizations within the family.

Projects and Project Dates

Projects are attributed to organizations via organization_slug.

The Volunteer Data Model

The full data model context for organizations.
Last modified on May 22, 2026