The Organization resource — the parent-child ‘organization family’ hierarchy, the fields the live API returns, and the patterns for navigating multi-organization customer setups.
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 Organization (or family) accessible to the token
/organizations/{id}
GET
A single Organization with its parent/child relationships
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.
VOMO Organizations support custom display labels that override the default UI vocabulary:
Field
Default
Example custom values
groups_moniker
"Group"
"Team", "Chapter", "Cohort"
project_moniker
"Project"
"Opportunity", "Event", "Activity"
campaign_moniker
"Campaign"
"Initiative", "Drive", "Mission"
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.”
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.
⚠️ 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
async function getOrganizationFamily() { const response = await fetch( 'https://api.vomo.org/v1/organizations', { headers: { Authorization: `Bearer ${token}` } } ); if (!response.ok) throw new Error(`Failed: ${response.status}`); const result = await response.json(); return result.data;}
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.
// Aggregate across the entire family (default token scope)async function totalActiveProjectsAcrossFamily() { const params = new URLSearchParams({ active: 'true', published: 'true' }); const all = await paginate(`https://api.vomo.org/v1/projects?${params}`); return all.length;}// Filter to one specific orgasync function activeProjectsForOrg(orgSlug) { const params = new URLSearchParams({ active: 'true', published: 'true', org_slug: orgSlug, }); return paginate(`https://api.vomo.org/v1/projects?${params}`);}// Filter to multiple specific orgsasync function activeProjectsForOrgs(orgSlugs) { const params = new URLSearchParams({ active: 'true', published: 'true', org_slug: orgSlugs.join(','), }); return paginate(`https://api.vomo.org/v1/projects?${params}`);}
The org_slug parameter on Project and Campaign endpoints is the canonical way to filter — comma-separated lists are supported.
The Organization the API token was issued for is typically the parent. To detect it programmatically:
JavaScript
async function getHomeOrganization() { const family = await getOrganizationFamily(); // If the family response returns a single Organization, that's the home // If it returns a hierarchy, the root (no parent_organizations) is the home if (Array.isArray(family.parent_organizations) && family.parent_organizations.length === 0) { return family; } // ...otherwise navigate up to the topmost org return family;}
Useful for displaying “you’re integrated with [Home Org Name]” in your partner UI.
A few practical points about Organization identifiers:
Identifier
When to use
id (integer)
Direct API references — GET /organizations/{id}
slug (string)
Filter parameters — ?org_slug=wayne-foundation
name (string)
Display only — never used as a key
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).
The org_slug query parameter on Project and Campaign endpoints accepts comma-separated values:
GET /projects?org_slug=gotham-outreach,wayne-manor-programs
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.
Partner integrations serving customers with parent-child organization structures should:
Practice
Description
Surface the family structure in your UI
Let the customer see what organizations the integration has access to
Allow per-org configuration where it makes sense
Different child orgs may have different sync destinations, templates, or rules
Use slug-based filtering for routing
Easier to read in code and configuration than numeric IDs
Honor monikers in user-facing displays
The customer customized the labels for a reason
Don’t assume one-token-equals-one-org
Multi-org customers’ single token can span many organizations
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.
The ?? null and ?? defaults throughout reflect the spec gap reality — fields may be missing or have unexpected shapes, and the parser handles both gracefully.