{ "openapi": "3.0.0", "info": { "title": "VOMO API", "description": "\n# Welcome to the VOMO Client API\n\nThe VOMO Client API is a REST-based and allows you to query and pull certain aspects of your data wihin VOMO. API access can be enabled for any VOMO client. Please talk with your account concierge to have this enabled.\n\n## Authentication\n\nAuthentication to the VOMO API is handled via a Bearer token in the Authorization header. Tokens can be created in the admin portal once API access is enabled for your account. The authorization header should look like the following once complete.\n\n```\nAuthorization: Bearer eyJhbGci.....yu5CSpyHI\n```\n\nIETF Standard: [https://tools.ietf.org/html/rfc6750](https://tools.ietf.org/html/rfc6750)\n\n- - -\n\n ", "termsOfService": "https://www.vomo.org/terms-of-service/", "contact": { "name": "VOMO", "url": "https://vomo.org", "email": "support@vomo.org" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.vomo.org/v1", "description": "VOMO Volunteer API (production)" } ], "paths": { "/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List / find Campaigns", "description": "Returns a paginated list of all campaigns belonging to your organization family. Use this endpoint to sync campaign records into an external system or to look up campaigns by name. You can scope results to specific organizations using the org_slug filter, or narrow by creation and update timestamps to retrieve only recently changed records.", "operationId": "listCampaigns", "parameters": [ { "name": "page", "in": "query", "description": "Page number (if paging results).", "required": false, "schema": { "type": "integer" } }, { "name": "org_slug", "in": "query", "description": "One or more org slugs (comma separated) campaigns should belong to.", "required": false, "schema": { "type": "string" } }, { "name": "name_like", "in": "query", "description": "The campaign name, or part of a name, to search for.", "required": false, "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "description": "Date the campaign was created on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_after", "in": "query", "description": "Date the campaign was created on or after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "description": "Date the campaign was updated on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Date the campaign was updated on or after", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Returns the paginated list of campaigns for your organization family. The response includes pagination links and meta fields to navigate additional pages.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "type": "campaign", "id": "91", "campaign_name": "Fall Hunger Relief Drive", "description": "A coordinated effort to stock local food banks before winter.", "url": "https://app.vomo.org/initiative/fall-hunger-relief-drive", "organization": "Riverside Hope Foundation", "organization_slug": "riverside-hope", "organization_id": 50, "author_id": 7903, "logo_url": null, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:00:00+00:00" }, { "type": "campaign", "id": "92", "campaign_name": "Youth Leadership Initiative", "description": "Empowering young volunteers with leadership skills.", "url": "https://app.vomo.org/initiative/youth-leadership-initiative", "organization": "Riverside Hope Youth Programs", "organization_slug": "riverside-hope-youth", "organization_id": 51, "author_id": 7821, "logo_url": null, "created_at": "2025-11-03T10:00:00+00:00", "updated_at": "2025-11-03T10:00:00+00:00" } ], "links": { "first": "https://api.vomo.org/v1/campaigns?page=1", "last": "https://api.vomo.org/v1/campaigns?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "to": 4, "path": "https://api.vomo.org/v1/campaigns", "per_page": 15, "total": 4 } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get Campaign Details", "description": "Returns the full detail record for a single campaign, including its associated projects and their dates. The campaign must belong to your organization family; requests for campaigns outside your family return a 400 error.", "operationId": "showCampaign", "parameters": [ { "name": "id", "in": "path", "description": "The unique VOMO identifier for the campaign to retrieve.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the full campaign record, including all associated projects and their serving dates.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CampaignDetailResource" } }, "type": "object" }, "example": { "data": { "type": "campaign", "campaign_id": "91", "campaign_name": "Fall Hunger Relief Drive", "description": "A coordinated effort to stock local food banks before winter.", "url": "https://app.vomo.org/initiative/fall-hunger-relief-drive", "organization": "Riverside Hope Foundation", "organization_slug": "riverside-hope", "organization_id": 50, "author_id": 7903, "logo_url": null, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:00:00+00:00", "projects": [ { "type": "project", "id": "4001", "project_name": "Saturday Pantry Pack", "description": "Pack weekend food bags for students at risk of hunger.", "details": "Wear closed-toe shoes. Bring a water bottle.", "url": "https://app.vomo.org/opportunity/saturday-pantry-pack", "organization_id": 50, "organization": "Riverside Hope Foundation", "organization_slug": "riverside-hope", "author_id": 7903, "owners": [ { "id": 7903, "is_primary_owner": true, "send_notifications": true } ], "address": { "lat": "33.214561", "lng": "-96.614456", "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "anytime": 0, "anywhere": 0, "draft": false, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:22:00+00:00", "published_at": "2025-11-01T09:00:00+00:00", "campaigns": [ { "type": "campaign", "id": "91", "campaign_name": "Fall Hunger Relief Drive", "description": "A coordinated effort to stock local food banks before winter.", "url": "https://app.vomo.org/initiative/fall-hunger-relief-drive", "organization": "Riverside Hope Foundation", "organization_slug": "riverside-hope", "organization_id": 50, "author_id": 7903, "logo_url": null, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:00:00+00:00" } ], "certificates": [], "form_completions": [], "next_date": { "type": "project_date", "id": 40001, "starts_at": "2025-11-15T09:00:00+00:00", "ends_at": "2025-11-15T12:00:00+00:00", "participant_count": 8 }, "images": [ "https://vomo-cdn.com/media/2025/11/pantry-pack-l.jpg" ], "point_person": { "name": "Priya Sharma", "phone": "(555) 012-0103", "email": "priya.sharma@example.org" }, "allow_guests": true, "age_limit": 0, "volunteer_question": null, "participant_approval_required": false, "background_check_required": false, "show_volunteer_counter": false, "volunteer_counter_threshold": 0, "privacy": "PUBLIC", "all_dates": [ { "type": "project_date", "id": 40001, "starts_at": "2025-11-15T09:00:00+00:00", "ends_at": "2025-11-15T12:00:00+00:00", "participant_count": 8 } ] } ] } } } } }, "400": { "description": "The requested campaign exists but does not belong to your organization family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 400, "message": "No query results" } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No campaign exists with the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "No query results for model [App\\\\Models\\\\Campaign]." } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/certificates": { "get": { "tags": [ "Certifications" ], "summary": "Get all certifications", "description": "Returns a paginated list of all certifications defined for your organization. Use this endpoint to sync certification records into an external system or to look up certifications by name. Filter by name, creation date, or last-updated date to retrieve only the records relevant to your integration.", "operationId": "listCertifications", "parameters": [ { "name": "name_like", "in": "query", "description": "The certification name, or part of a name, to search for.", "required": false, "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "description": "Date the Certification was created on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_after", "in": "query", "description": "Date the Certification was created on or after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "description": "Date the Certification was updated on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Date the Certification was updated on or after", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Returns the paginated list of certifications for your organization. The response includes pagination links and meta fields to navigate additional pages.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "id": 101, "name": "Safe Food Handling", "requirement": "Complete the online food safety module and pass the quiz.", "slug": "a1b2c3d4-safe-food-handling", "expiration_in_months": 12, "creator_id": 7903, "organization_id": 50, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-01T09:00:00+00:00" }, { "id": 102, "name": "Volunteer Orientation", "requirement": "Attend a 1-hour orientation session.", "slug": "b2c3d4e5-volunteer-orientation", "expiration_in_months": null, "creator_id": 7903, "organization_id": 50, "created_at": "2025-11-02T10:00:00+00:00", "updated_at": "2025-11-02T10:00:00+00:00" } ], "links": { "first": "https://api.vomo.org/v1/certificates?page=1", "last": "https://api.vomo.org/v1/certificates?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "to": 3, "path": "https://api.vomo.org/v1/certificates", "per_page": 15, "total": 3 } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/forms": { "get": { "tags": [ "Forms" ], "summary": "Get all forms", "description": "Returns a paginated list of all forms for your organization. By default, archived (soft-deleted) forms are excluded; pass include_archived=true to include them. Use the date filters to retrieve only forms created or updated within a specific time window.", "operationId": "listForms", "parameters": [ { "name": "name_like", "in": "query", "description": "The form name, or part of a name, to search for.", "required": false, "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "description": "Date the Form was created on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_after", "in": "query", "description": "Date the Form was created on or after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "description": "Date the Form was updated on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Date the Form was updated on or after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "include_archived", "in": "query", "description": "This flag will include archived forms.", "required": false, "schema": { "type": "string", "default": "false", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Returns the paginated list of forms for your organization. The response includes pagination links and meta fields to navigate additional pages.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "type": "form", "id": 2001, "name": "Volunteer Application", "form_type": "REGISTRATION", "slug": "c3d4e5f6-volunteer-application", "description": "Standard application required for all new volunteers.", "author_id": 7903, "organization_id": 50, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-01T09:00:00+00:00", "deleted_at": null, "fields": [ { "name": "T-Shirt Size", "description": "Please select your T-shirt size.", "field_type": "DROPDOWN", "slug": "d4e5f6a7-tshirt-size", "show_in_profile": true, "options": [ { "type": "field_option", "id": 3001, "name": "Small", "value": "S", "enabled": true, "weight": 0 }, { "type": "field_option", "id": 3002, "name": "Medium", "value": "M", "enabled": true, "weight": 1 }, { "type": "field_option", "id": 3003, "name": "Large", "value": "L", "enabled": true, "weight": 2 } ] } ] }, { "type": "form", "id": 2002, "name": "Food Pantry Waiver", "form_type": "PROJECT", "slug": "e5f6a7b8-food-pantry-waiver", "description": "Liability waiver for food pantry volunteers.", "author_id": 7903, "organization_id": 50, "created_at": "2025-11-03T11:00:00+00:00", "updated_at": "2025-11-03T11:00:00+00:00", "deleted_at": null, "fields": [ { "name": "I agree to the waiver terms", "description": null, "field_type": "WAIVER", "slug": "f6a7b8c9-waiver-terms", "show_in_profile": false, "options": [] } ] } ], "links": { "first": "https://api.vomo.org/v1/forms?page=1", "last": "https://api.vomo.org/v1/forms?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "to": 5, "path": "https://api.vomo.org/v1/forms", "per_page": 15, "total": 5 } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{id}/completions": { "get": { "tags": [ "Forms" ], "summary": "Get all completions for a form", "description": "Returns a paginated list of all completions for the specified form. Use this endpoint to pull volunteer responses, survey submissions, or waiver completions associated with a form. Filter by user_id to retrieve completions for a specific volunteer, or use the date filters to retrieve only recently submitted or modified completions.", "operationId": "completions.index", "parameters": [ { "name": "user_id", "in": "query", "description": "Find completions of this form for a given User ID.", "required": false, "schema": { "type": "integer" } }, { "name": "created_before", "in": "query", "description": "Date the Form Completion was created on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_after", "in": "query", "description": "Date the Form Completion was created on or after.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "description": "Date the Form Completion was updated on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Date the Form Completion was updated on or after.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "id", "in": "path", "description": "VOMO Form ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the paginated list of form completions for the specified form. The response includes pagination links and meta fields to navigate additional pages.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormCompletionResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "type": "form_completion", "id": 70001, "form_id": 2001, "user_id": 7903, "project_id": null, "participation_id": null, "field_responses": [ { "type": "form_field_response", "id": 80001, "form_completion_id": 70001, "user_id": 7903, "field_id": 5001, "value": "M" } ], "created_at": "2025-11-05T10:00:00+00:00", "updated_at": "2025-11-05T10:00:00+00:00" }, { "type": "form_completion", "id": 70002, "form_id": 2001, "user_id": 8104, "project_id": null, "participation_id": null, "field_responses": [ { "type": "form_field_response", "id": 80002, "form_completion_id": 70002, "user_id": 8104, "field_id": 5001, "value": "S" } ], "created_at": "2025-11-06T09:30:00+00:00", "updated_at": "2025-11-06T09:30:00+00:00" } ], "links": { "first": "https://api.vomo.org/v1/forms/2001/completions?page=1", "last": "https://api.vomo.org/v1/forms/2001/completions?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "to": 14, "path": "https://api.vomo.org/v1/forms/2001/completions", "per_page": 15, "total": 14 } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No form exists with the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Not Found" } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{id}/completions/{completion}": { "get": { "tags": [ "Forms" ], "summary": "Get a single form completion", "description": "Returns the full detail record for a single form completion, including all field responses submitted by the volunteer. Use this endpoint to retrieve the specific answers a user provided when completing a form.", "operationId": "completions.show", "parameters": [ { "name": "id", "in": "path", "description": "The unique VOMO identifier for the form.", "required": true, "schema": { "type": "integer" } }, { "name": "completion", "in": "path", "description": "The unique VOMO identifier for the form completion record to retrieve.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the full form completion record, including all field responses submitted by the volunteer.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/FormCompletionResource" } }, "type": "object" }, "example": { "data": { "type": "form_completion", "id": 70001, "form_id": 2001, "user_id": 7903, "project_id": null, "participation_id": null, "field_responses": [ { "type": "form_field_response", "id": 80001, "form_completion_id": 70001, "user_id": 7903, "field_id": 5001, "value": "M" } ], "created_at": "2025-11-05T10:00:00+00:00", "updated_at": "2025-11-05T10:00:00+00:00" } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No form or form completion exists with the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Not Found" } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/groups": { "get": { "tags": [ "Groups" ], "summary": "Get all groups", "description": "Returns a paginated list of all groups for your organization. Use this endpoint to sync group records into an external system or to find groups by name or parent. Filter by parent_id to retrieve only direct child groups of a specific group, or use the date filters to retrieve only recently created or modified groups.", "operationId": "listGroups", "parameters": [ { "name": "name_like", "in": "query", "description": "The group name, or part of a name, to search for.", "required": false, "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "description": "Filter results to only groups that are direct children of the group with this ID. Provide the VOMO Group ID of the parent group.", "required": false, "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "description": "Date the Group was created on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_after", "in": "query", "description": "Date the Group was created on or after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "description": "Date the Group was updated on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Date the Group was updated on or after", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Returns the paginated list of groups for your organization. The response includes pagination links and meta fields to navigate additional pages.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "id": 601, "name": "Saturday Morning Crew", "description": "Volunteers who serve on Saturday mornings.", "parent_id": null, "has_subgroups": false, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-01T09:00:00+00:00" }, { "id": 602, "name": "Food Pantry Team", "description": "Core team for food pantry operations.", "parent_id": null, "has_subgroups": true, "created_at": "2025-11-02T10:00:00+00:00", "updated_at": "2025-11-10T08:00:00+00:00" } ], "links": { "first": "https://api.vomo.org/v1/groups?page=1", "last": "https://api.vomo.org/v1/groups?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "to": 8, "path": "https://api.vomo.org/v1/groups", "per_page": 15, "total": 8 } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Groups" ], "summary": "Create New Group", "description": "Creates a new group within your organization. Supply a name for the group. Optionally provide created_by_user_id (the VOMO user ID of the group owner, who must be a member of your organization), a parent_id to nest the group under an existing group, and a members array of user IDs to immediately add members upon creation.", "operationId": "createGroup", "requestBody": { "description": "Group to create", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupWriteRequest" } } } }, "responses": { "200": { "description": "Returns the newly created group record. Note: on success this endpoint returns 200 OK, not 201 Created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/GroupResource" } }, "type": "object" }, "example": { "data": { "id": 604, "name": "Weekend Warriors", "description": "Volunteers available on weekends.", "parent_id": null, "has_subgroups": false, "created_at": "2025-11-21T09:00:00+00:00", "updated_at": "2025-11-21T09:00:00+00:00" } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "422": { "description": "One or more request fields failed validation. Check the errors map for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/groups/{id}": { "get": { "tags": [ "Groups" ], "summary": "Get A Group", "description": "Returns the full detail record for a single group, including its parent group and any direct child (sub)groups. Use this endpoint to inspect a group's hierarchy and metadata before modifying its membership or settings.", "operationId": "showGroup", "parameters": [ { "name": "id", "in": "path", "description": "VOMO Group ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the group record, including its parent group (if any) and any direct child subgroups.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupResource" }, { "properties": { "subgroups": { "description": "Child groups of this group", "type": "array", "items": { "$ref": "#/components/schemas/GroupResource" } }, "parent": { "$ref": "#/components/schemas/GroupResource" } }, "type": "object" } ] } }, "type": "object" }, "example": { "data": { "id": 602, "name": "Food Pantry Team", "description": "Core team for food pantry operations.", "parent_id": null, "has_subgroups": true, "subgroups": [ { "id": 603, "name": "Food Pantry - Intake", "description": "Handles intake and sorting.", "parent_id": 602, "has_subgroups": false, "created_at": "2025-11-05T09:00:00+00:00", "updated_at": "2025-11-05T09:00:00+00:00" } ], "parent": null, "created_at": "2025-11-02T10:00:00+00:00", "updated_at": "2025-11-10T08:00:00+00:00" } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No group with the provided ID exists in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Group not found in your organization." } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Groups" ], "summary": "Update A Group", "description": "Updates the properties of an existing group. You must supply at least the group name. Provide a parent_id to change the group's parent. If a members array is supplied it REPLACES the group's entire membership with exactly those user IDs (members omitted from the array are removed) — to adjust membership, send the full intended member list, or use the dedicated members endpoint.", "operationId": "updateGroup", "parameters": [ { "name": "id", "in": "path", "description": "VOMO Group ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Group fields to update", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupWriteRequest" } } } }, "responses": { "200": { "description": "Returns the updated group record with all current field values.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/GroupResource" } }, "type": "object" }, "example": { "data": { "id": 604, "name": "Weekend Warriors — Updated", "description": "Volunteers available on weekends for any project.", "parent_id": null, "has_subgroups": false, "created_at": "2025-11-21T09:00:00+00:00", "updated_at": "2025-11-22T11:00:00+00:00" } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No group with the provided ID exists in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Group not found in your organization." } } } }, "422": { "description": "One or more request fields failed validation. Check the errors map for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/groups/{id}/members": { "get": { "tags": [ "Groups" ], "summary": "Get Group Members", "description": "Returns a paginated list of all users who are members of the specified group. Use this endpoint to inspect current group membership before making changes, or to sync group membership data into an external system.", "operationId": "members.index", "parameters": [ { "name": "id", "in": "path", "description": "The unique VOMO identifier for the group whose members to retrieve.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the paginated list of users who are members of this group. The response includes pagination links and meta fields to navigate additional pages.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "type": "user", "id": "7903", "first_name": "Priya", "last_name": "Sharma", "full_name": "Priya Sharma", "email": "priya.sharma@example.org", "address": "123 Maple Ave, McKinney, TX 75069, USA", "phone": "(555) 012-0103", "birthday": "1990-03-15", "gender": "F", "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:22:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "ORGANIZER" }, { "type": "user", "id": "8104", "first_name": "Aisha", "last_name": "Mohamed", "full_name": "Aisha Mohamed", "email": "aisha.mohamed@example.org", "address": "789 Birch Dr, McKinney, TX 75069, USA", "phone": "(555) 012-0104", "birthday": "1993-11-08", "gender": "F", "created_at": "2025-11-03T11:00:00+00:00", "updated_at": "2025-11-03T11:00:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "VOLUNTEER" } ], "links": { "first": "https://api.vomo.org/v1/groups/602/members?page=1", "last": "https://api.vomo.org/v1/groups/602/members?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "to": 2, "path": "https://api.vomo.org/v1/groups/602/members", "per_page": 15, "total": 2 } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No group with the provided ID exists in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Group not found in your organization." } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Groups" ], "summary": "Update A Group's Members", "description": "Replaces the specified group's membership with exactly the set of user IDs provided. This is NOT additive: any current member whose ID is omitted is removed from the group, and the supplied IDs become the complete membership. All provided user IDs must be members of your organization. Returns the updated paginated list of group members after the change.", "operationId": "members.update", "parameters": [ { "name": "id", "in": "path", "description": "The unique VOMO identifier for the group whose membership to update.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "The complete set of user IDs that should make up the group's membership after the request.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembersWriteRequest" } } } }, "responses": { "200": { "description": "Returns the updated paginated list of group members after the membership has been replaced.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "type": "user", "id": "7903", "first_name": "Priya", "last_name": "Sharma", "full_name": "Priya Sharma", "email": "priya.sharma@example.org", "address": "123 Maple Ave, McKinney, TX 75069, USA", "phone": "(555) 012-0103", "birthday": "1990-03-15", "gender": "F", "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:22:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "ORGANIZER" }, { "type": "user", "id": "8412", "first_name": "Devon", "last_name": "Park", "full_name": "Devon Park", "email": "devon.park@example.org", "address": "987 Cedar Way, McKinney, TX 75069, USA", "phone": "(555) 012-0112", "birthday": "1998-04-20", "gender": "O", "created_at": "2025-11-06T09:00:00+00:00", "updated_at": "2025-11-22T10:00:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "VOLUNTEER" } ], "links": { "first": "https://api.vomo.org/v1/groups/602/members?page=1", "last": "https://api.vomo.org/v1/groups/602/members?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "to": 2, "path": "https://api.vomo.org/v1/groups/602/members", "per_page": 15, "total": 2 } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No group with the provided ID exists in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Group not found in your organization." } } } }, "422": { "description": "One or more user IDs failed validation. This occurs when a provided ID does not exist or the user is not a member of your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "members.0": [ "Member not found." ] } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/organizations": { "get": { "tags": [ "Organizations" ], "summary": "Get details for organizations in your organizations family", "description": "Returns all organizations in your organization family — your own organization together with its parent and child organizations. Use this endpoint to discover which organizations are available to your integration and to retrieve their IDs and metadata. Results are not paginated — the full family list is returned in a single response.", "operationId": "listOrganizations", "responses": { "200": { "description": "Returns the list of all organizations in your organization family — your own organization together with its parent and child organizations.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResource" } } }, "type": "object" }, "example": { "data": [ { "id": 50, "name": "Riverside Hope Foundation", "slug": "riverside-hope", "type": "NPO", "description": "A nonprofit dedicated to eliminating food insecurity in North Texas.", "email": "info@riversidehope.example.org", "phone": "(555) 012-0100", "website": "https://riversidehope.example.org", "tax_number": "75-0000050", "org_size": 250, "background_check_expiration": "1_YEAR", "background_check_expiration_mode": "relative", "background_check_absolute_expiration": null, "invitation_token": "RHFMAIN", "address": { "lat": 33.214561, "lng": -96.614456, "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "groups_moniker": "Group", "giving_enabled": false, "created_at": "2025-11-01 09:00:00", "updated_at": "2025-11-10 14:00:00", "deleted_at": null, "show_categories": 1, "show_rewards": 0, "project_moniker": "Project", "campaign_moniker": "Campaign", "user_submitted_projects": 0, "logo": null }, { "id": 51, "name": "Riverside Hope Youth Programs", "slug": "riverside-hope-youth", "type": "NPO", "description": "Youth volunteer and mentorship programs.", "email": "youth@riversidehope.example.org", "phone": "(555) 012-0101", "website": null, "tax_number": null, "org_size": 80, "background_check_expiration": "1_YEAR", "background_check_expiration_mode": "relative", "background_check_absolute_expiration": null, "invitation_token": "RHFYOUTH", "address": { "lat": 33.214561, "lng": -96.614456, "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "groups_moniker": "Group", "giving_enabled": false, "created_at": "2025-11-02 10:00:00", "updated_at": "2025-11-02 10:00:00", "deleted_at": null, "show_categories": 1, "show_rewards": 0, "project_moniker": "Project", "campaign_moniker": "Campaign", "user_submitted_projects": 0, "logo": null }, { "id": 52, "name": "Riverside Hope Food Distribution", "slug": "riverside-hope-food", "type": "NPO", "description": "Mobile food pantry and meal delivery operations.", "email": "food@riversidehope.example.org", "phone": "(555) 012-0102", "website": null, "tax_number": null, "org_size": 120, "background_check_expiration": "1_YEAR", "background_check_expiration_mode": "relative", "background_check_absolute_expiration": null, "invitation_token": "RHFFOOD", "address": { "lat": 33.214561, "lng": -96.614456, "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "groups_moniker": "Group", "giving_enabled": false, "created_at": "2025-11-02 11:00:00", "updated_at": "2025-11-02 11:00:00", "deleted_at": null, "show_categories": 1, "show_rewards": 0, "project_moniker": "Project", "campaign_moniker": "Campaign", "user_submitted_projects": 0, "logo": null } ] } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Organizations" ], "summary": "Create a new Organization", "description": "Creates a new Organization and attaches it to the requesting partner's family. This endpoint is restricted to an authorized partner integration — all other callers receive a 403.", "operationId": "createOrganization", "requestBody": { "description": "Organization to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationWriteRequest" } } } }, "responses": { "200": { "description": "Returns the newly created organization record, including its generated slug and all default field values. The organization is automatically linked as a child of your partner organization. Note: on success this endpoint returns 200 OK, not 201 Created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/OrganizationResource" } }, "type": "object" }, "example": { "data": { "id": 53, "name": "Riverside Hope East Campus", "slug": "riverside-hope-east", "type": "NPO", "description": "East campus community programs.", "email": "east@riversidehope.example.org", "phone": "(555) 012-0105", "website": null, "tax_number": null, "org_size": 60, "background_check_expiration": "1_YEAR", "background_check_expiration_mode": "relative", "background_check_absolute_expiration": null, "invitation_token": "RHFEAST", "address": { "lat": 33.219, "lng": -96.6, "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75071", "country_short": "US", "locality_short": "McKinney", "formatted_address": "200 Redbud Blvd, McKinney, TX 75071, USA", "postal_code_short": "75071", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "groups_moniker": "Group", "giving_enabled": false, "created_at": "2025-11-20 09:00:00", "updated_at": "2025-11-20 09:00:00", "deleted_at": null, "show_categories": 1, "show_rewards": 0, "project_moniker": "Project", "campaign_moniker": "Campaign", "user_submitted_projects": 0, "logo": null, "child_organizations": [], "parent_organizations": [ { "id": 50, "name": "Riverside Hope Foundation", "slug": "riverside-hope", "type": "NPO", "description": "A nonprofit dedicated to eliminating food insecurity in North Texas.", "email": "info@riversidehope.example.org", "phone": "(555) 012-0100", "website": "https://riversidehope.example.org", "tax_number": "75-0000050", "org_size": 250, "background_check_expiration": "1_YEAR", "background_check_expiration_mode": "relative", "background_check_absolute_expiration": null, "invitation_token": "RHFMAIN", "address": { "lat": 33.214561, "lng": -96.614456, "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "groups_moniker": "Group", "giving_enabled": false, "created_at": "2025-11-01 09:00:00", "updated_at": "2025-11-10 14:00:00", "deleted_at": null, "show_categories": 1, "show_rewards": 0, "project_moniker": "Project", "campaign_moniker": "Campaign", "user_submitted_projects": 0, "logo": null } ] } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "403": { "description": "Your API key is not authorized to create organizations. Only approved partner integrations may call this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "This action is unauthorized." } } } }, "422": { "description": "One or more request fields failed validation. Check the errors map for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "name": [ "The name field is required." ], "address": [ "The address field is required." ] } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/organizations/{id}": { "get": { "tags": [ "Organizations" ], "summary": "Get Organization Details", "description": "Returns the full detail record for a single organization, including its child and parent organization relationships. The requested organization must belong to your organization family; requests for organizations outside your family return a 404.", "operationId": "showOrganization", "parameters": [ { "name": "id", "in": "path", "description": "The unique VOMO identifier for the organization to retrieve.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the full organization record, including its child and parent organization relationships.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/OrganizationResource" } }, "type": "object" }, "example": { "data": { "id": 50, "name": "Riverside Hope Foundation", "slug": "riverside-hope", "type": "NPO", "description": "A nonprofit dedicated to eliminating food insecurity in North Texas.", "email": "info@riversidehope.example.org", "phone": "(555) 012-0100", "website": "https://riversidehope.example.org", "tax_number": "75-0000050", "org_size": 250, "background_check_expiration": "1_YEAR", "background_check_expiration_mode": "relative", "background_check_absolute_expiration": null, "invitation_token": "RHFMAIN", "address": { "lat": 33.214561, "lng": -96.614456, "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "groups_moniker": "Group", "giving_enabled": false, "created_at": "2025-11-01 09:00:00", "updated_at": "2025-11-10 14:00:00", "deleted_at": null, "show_categories": 1, "show_rewards": 0, "project_moniker": "Project", "campaign_moniker": "Campaign", "user_submitted_projects": 0, "logo": null, "child_organizations": [ { "id": 51, "name": "Riverside Hope Youth Programs", "slug": "riverside-hope-youth", "type": "NPO", "description": "Youth volunteer and mentorship programs.", "email": "youth@riversidehope.example.org", "phone": "(555) 012-0101", "website": null, "tax_number": null, "org_size": 80, "background_check_expiration": "1_YEAR", "background_check_expiration_mode": "relative", "background_check_absolute_expiration": null, "invitation_token": "RHFYOUTH", "address": { "lat": 33.214561, "lng": -96.614456, "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "groups_moniker": "Group", "giving_enabled": false, "created_at": "2025-11-02 10:00:00", "updated_at": "2025-11-02 10:00:00", "deleted_at": null, "show_categories": 1, "show_rewards": 0, "project_moniker": "Project", "campaign_moniker": "Campaign", "user_submitted_projects": 0, "logo": null }, { "id": 52, "name": "Riverside Hope Food Distribution", "slug": "riverside-hope-food", "type": "NPO", "description": "Mobile food pantry and meal delivery operations.", "email": "food@riversidehope.example.org", "phone": "(555) 012-0102", "website": null, "tax_number": null, "org_size": 120, "background_check_expiration": "1_YEAR", "background_check_expiration_mode": "relative", "background_check_absolute_expiration": null, "invitation_token": "RHFFOOD", "address": { "lat": 33.214561, "lng": -96.614456, "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "groups_moniker": "Group", "giving_enabled": false, "created_at": "2025-11-02 11:00:00", "updated_at": "2025-11-02 11:00:00", "deleted_at": null, "show_categories": 1, "show_rewards": 0, "project_moniker": "Project", "campaign_moniker": "Campaign", "user_submitted_projects": 0, "logo": null } ], "parent_organizations": [] } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "The requested organization does not exist or is not in your organization family.", "content": { "application/json": { "schema": { "required": [ "error", "message" ], "properties": { "error": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Not found" } }, "type": "object" } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/projects": { "get": { "tags": [ "Projects" ], "summary": "List / find Projects", "description": "Returns a paginated list of volunteer projects belonging to your organization family. No status filter is applied unless requested: pass the active, published, and/or anytime flags to restrict results by those attributes. Filter by org_slug, name, date range, or event date range to narrow results for a specific integration use case.", "operationId": "listProjects", "parameters": [ { "name": "page", "in": "query", "description": "Page number (if paging results).", "required": false, "schema": { "type": "integer" } }, { "name": "active", "in": "query", "description": "When set to true, limits results to currently active projects; when set to false, to past projects. Omit the parameter to return projects regardless of state — no filter is applied by default.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "published", "in": "query", "description": "When set to true, limits results to published projects; when set to false, to unpublished (draft) projects. Omit the parameter to return projects regardless of publish state — no filter is applied by default.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "anytime", "in": "query", "description": "When set to true, limits results to anytime (open-ended) projects; when set to false, to projects with definite scheduled times. Omit the parameter to return both — no filter is applied by default.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "org_slug", "in": "query", "description": "One or more org slugs (comma separated) projects should belong to.", "required": false, "schema": { "type": "string" } }, { "name": "name_like", "in": "query", "description": "The project name, or part of a name, to search for.", "required": false, "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "description": "Date the Project was created on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_after", "in": "query", "description": "Date the Project was created on or after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "description": "Date the Project was updated on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Date the Project was updated on or after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "dates_before", "in": "query", "description": "Projects that have dates that started at or before the given date and time", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "dates_after", "in": "query", "description": "Projects that have dates that started at or after the given date and time", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Returns the paginated list of projects for your organization family, filtered by the provided query parameters. The response includes pagination links and meta fields to navigate additional pages.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "type": "project", "id": "4001", "project_name": "Saturday Pantry Pack", "description": "Pack weekend food bags for students at risk of hunger.", "details": "Wear closed-toe shoes. Bring a water bottle.", "url": "https://app.vomo.org/opportunity/saturday-pantry-pack", "organization_id": 50, "organization": "Riverside Hope Foundation", "organization_slug": "riverside-hope", "author_id": 7903, "owners": [ { "id": 7903, "is_primary_owner": true, "send_notifications": true } ], "address": { "lat": "33.214561", "lng": "-96.614456", "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "anytime": 0, "anywhere": 0, "draft": false, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:22:00+00:00", "published_at": "2025-11-01T09:00:00+00:00", "campaigns": [], "certificates": [], "form_completions": [], "next_date": { "type": "project_date", "id": 40001, "starts_at": "2025-11-15T09:00:00+00:00", "ends_at": "2025-11-15T12:00:00+00:00", "participant_count": 8 }, "images": [ "https://vomo-cdn.com/media/2025/11/pantry-pack-l.jpg" ] }, { "type": "project", "id": "4002", "project_name": "Neighborhood Cleanup Drive", "description": "Beautify local parks and streetways across McKinney.", "details": null, "url": "https://app.vomo.org/opportunity/neighborhood-cleanup-drive", "organization_id": 50, "organization": "Riverside Hope Foundation", "organization_slug": "riverside-hope", "author_id": 7821, "owners": [ { "id": 7821, "is_primary_owner": true, "send_notifications": true } ], "address": { "lat": "33.196800", "lng": "-96.615400", "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "Oak St Park, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "anytime": 0, "anywhere": 0, "draft": false, "created_at": "2025-11-03T10:15:00+00:00", "updated_at": "2025-11-07T08:00:00+00:00", "published_at": "2025-11-03T10:15:00+00:00", "campaigns": [], "certificates": [], "form_completions": [], "next_date": { "type": "project_date", "id": 40002, "starts_at": "2025-11-22T08:00:00+00:00", "ends_at": "2025-11-22T11:00:00+00:00", "participant_count": 12 }, "images": [] } ], "links": { "first": "https://api.vomo.org/v1/projects?page=1", "last": "https://api.vomo.org/v1/projects?page=3", "prev": null, "next": "https://api.vomo.org/v1/projects?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 3, "to": 15, "path": "https://api.vomo.org/v1/projects", "per_page": 15, "total": 34 } } } } }, "401": { "description": "Authentication credentials are missing or invalid. Ensure you are sending a valid Bearer token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Projects" ], "summary": "Create a Project", "description": "Creates a new volunteer project (opportunity) for your organization. Required fields are name, description, age_limit, privacy, allow_guests, participant_approval_required, and address (including address.timezone). Provide a dates array of serving dates for scheduled ('dated') projects; volunteer_question, campaigns, links, and point_person are optional. A project's type ('dated' vs 'anytime') cannot be changed after creation.", "operationId": "createProject", "requestBody": { "description": "Project to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWriteRequest" } } } }, "responses": { "201": { "description": "Returns the newly created project record in full detail, including its generated serving dates and any associated campaigns.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 201 }, "message": { "type": "string", "example": "Project created." }, "data": { "$ref": "#/components/schemas/ProjectDetailResource" } }, "type": "object" }, "example": { "code": 201, "message": "Project created.", "data": { "type": "project", "id": "4003", "project_name": "Holiday Gift Drive", "description": "Wrap and distribute holiday gifts to children in need.", "details": "Please arrive 10 minutes early for orientation.", "url": "https://app.vomo.org/opportunity/holiday-gift-drive", "organization_id": 50, "organization": "Riverside Hope Foundation", "organization_slug": "riverside-hope", "author_id": 7903, "owners": [ { "id": 7903, "is_primary_owner": true, "send_notifications": true } ], "address": { "lat": "33.214561", "lng": "-96.614456", "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "anytime": 0, "anywhere": 0, "draft": false, "created_at": "2025-11-18T10:00:00+00:00", "updated_at": "2025-11-18T10:00:00+00:00", "published_at": "2025-11-18T10:00:00+00:00", "campaigns": [], "certificates": [], "form_completions": [], "next_date": { "type": "project_date", "id": 40003, "starts_at": "2025-12-13T09:00:00+00:00", "ends_at": "2025-12-13T13:00:00+00:00", "participant_count": 0 }, "images": [], "point_person": { "name": "Priya Sharma", "phone": "(555) 012-0103", "email": "priya.sharma@example.org" }, "allow_guests": true, "age_limit": 12, "volunteer_question": null, "participant_approval_required": false, "background_check_required": false, "show_volunteer_counter": false, "volunteer_counter_threshold": 0, "privacy": "PUBLIC", "all_dates": [ { "type": "project_date", "id": 40003, "starts_at": "2025-12-13T09:00:00+00:00", "ends_at": "2025-12-13T13:00:00+00:00", "participant_count": 0 } ] } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "422": { "description": "One or more request fields failed validation. Check the errors map for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "name": [ "The name field is required." ], "address.timezone": [ "The address.timezone field is required." ] } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/projects/{id}": { "get": { "tags": [ "Projects" ], "summary": "Get Project Details", "description": "Returns the full detail record for a single volunteer project, including all serving dates, associated campaigns, and images. The project must belong to your organization family; requests for projects outside your family return a 400 error.", "operationId": "showProject", "parameters": [ { "name": "id", "in": "path", "description": "The unique VOMO identifier for the project to retrieve.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the full project detail record, including all serving dates, associated campaigns, and project images.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectDetailResource" } }, "links": { "properties": { "first": { "description": "A link to the first page of results", "type": "string", "example": "https://api.vomo.org/v1/projects?page=4" }, "last": { "description": "A link to the last page of results", "type": "string", "example": "https://api.vomo.org/v1/projects?page=4" }, "prev": { "description": "A link to the previous page of results", "type": "string", "example": "null" }, "next": { "description": "A link to the next page of results", "type": "string", "example": "https://api.vomo.org/v1/projects?page=2" } }, "type": "object" }, "meta": { "properties": { "current_page": { "description": "The current page", "type": "integer", "example": "1" }, "from": { "description": "The index of the first result on this page", "type": "integer", "example": "1" }, "to": { "description": "The index of the last result on this page", "type": "integer", "example": "15" }, "path": { "description": "The base URL", "type": "string", "example": "https://api.vomo.org/v1/projects" }, "per_page": { "description": "The number of results per page", "type": "integer", "example": "15" }, "total": { "description": "The total number of results", "type": "integer", "example": "49" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "The requested project exists but does not belong to your organization family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 400, "message": "No query results" } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No project exists with the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "No query results for model [App\\\\Models\\\\Project]." } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Projects" ], "summary": "Update a Project", "description": "Updates an existing volunteer project. All required project fields must be supplied. Serving dates are upserted: a date with an existing id is updated, a date with no id is created, and a date is removed only when it is included with status 'deleted' — omitting a date from the request does NOT delete it. The project_type (dated vs. anytime) cannot be changed after creation.", "operationId": "updateProject", "parameters": [ { "name": "id", "in": "path", "description": "The ID for the project to be updated", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "Project to update", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWriteRequest" } } } }, "responses": { "200": { "description": "Returns the updated project record in full detail, reflecting all changes made in this request including any serving date additions, updates, or deletions.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Project updated." }, "data": { "$ref": "#/components/schemas/ProjectDetailResource" } }, "type": "object" }, "example": { "code": 200, "message": "Project updated.", "data": { "type": "project", "id": "4001", "project_name": "Saturday Pantry Pack", "description": "Pack weekend food bags for students at risk of hunger. New winter session added.", "details": "Wear closed-toe shoes. Bring a water bottle.", "url": "https://app.vomo.org/opportunity/saturday-pantry-pack", "organization_id": 50, "organization": "Riverside Hope Foundation", "organization_slug": "riverside-hope", "author_id": 7903, "owners": [ { "id": 7903, "is_primary_owner": true, "send_notifications": true } ], "address": { "lat": "33.214561", "lng": "-96.614456", "country": "United States", "locality": "McKinney", "timezone": "America/Chicago", "postal_code": "75069", "country_short": "US", "locality_short": "McKinney", "formatted_address": "610 Elm St, McKinney, TX 75069, USA", "postal_code_short": "75069", "administrative_area_level_1": "Texas", "administrative_area_level_1_short": "TX" }, "anytime": 0, "anywhere": 0, "draft": false, "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-20T11:30:00+00:00", "published_at": "2025-11-01T09:00:00+00:00", "campaigns": [], "certificates": [], "form_completions": [], "next_date": { "type": "project_date", "id": 40004, "starts_at": "2025-12-06T09:00:00+00:00", "ends_at": "2025-12-06T12:00:00+00:00", "participant_count": 0 }, "images": [ "https://vomo-cdn.com/media/2025/11/pantry-pack-l.jpg" ], "point_person": { "name": "Priya Sharma", "phone": "(555) 012-0103", "email": "priya.sharma@example.org" }, "allow_guests": true, "age_limit": 0, "volunteer_question": null, "participant_approval_required": false, "background_check_required": false, "show_volunteer_counter": false, "volunteer_counter_threshold": 0, "privacy": "PUBLIC", "all_dates": [ { "type": "project_date", "id": 40001, "starts_at": "2025-11-15T09:00:00+00:00", "ends_at": "2025-11-15T12:00:00+00:00", "participant_count": 8 }, { "type": "project_date", "id": 40004, "starts_at": "2025-12-06T09:00:00+00:00", "ends_at": "2025-12-06T12:00:00+00:00", "participant_count": 0 } ] } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No project exists with the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "No query results for model [App\\\\Models\\\\Project]." } } } }, "422": { "description": "One or more request fields failed validation. Check the errors map for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "name": [ "The name field is required." ], "address.timezone": [ "The address.timezone field is required." ] } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/projects/date/{id}": { "get": { "tags": [ "Projects" ], "summary": "Get Project Date Details", "description": "Returns the detail record for a single project serving date (also called a 'happening'), including the list of participants who signed up. The serving date must belong to a project in your organization; requests for dates outside your organization return a 400 error.", "operationId": "showProjectDate", "parameters": [ { "name": "id", "in": "path", "description": "The unique VOMO identifier for the project serving date to retrieve.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the serving date detail record, including its start and end times, participant count, and the list of participants with their check-in details and hours.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ProjectDateResource" } }, "type": "object" }, "example": { "data": { "type": "project_date", "id": "40001", "project_name": "Saturday Pantry Pack", "starts_at": "2025-11-15T09:00:00+00:00", "ends_at": "2025-11-15T12:00:00+00:00", "participant_count": 2, "participants": [ { "type": "user", "id": 7903, "email": "priya.sharma@example.org", "guests": 1, "checked_in_at": "2025-11-15T09:04:00+00:00", "checked_out_at": "2025-11-15T12:01:00+00:00", "signed_up_at": "2025-11-10T14:00:00+00:00", "hours": "3.00", "verified": 1, "role": "Packer", "project_id": 4001, "project_date_id": 40001, "form_completions": [] }, { "type": "user", "id": 8104, "email": "aisha.mohamed@example.org", "guests": 0, "checked_in_at": null, "checked_out_at": null, "signed_up_at": "2025-11-11T09:30:00+00:00", "hours": "3.00", "verified": 0, "role": "Volunteer", "project_id": 4001, "project_date_id": 40001, "form_completions": [] } ] } } } } }, "400": { "description": "The requested serving date exists but belongs to a project outside your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 400, "message": "No query results" } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No serving date exists with the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "No query results for model [App\\\\Models\\\\Happening]." } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/projects/today": { "get": { "tags": [ "Projects" ], "summary": "List of Projects and Volunteers for today.", "description": "Returns all volunteer projects happening today (based on your organization's timezone), along with the list of signed-up volunteers for each. Use this endpoint to display a real-time roster of today's serving events and attendees, for example on a check-in kiosk or daily briefing report.", "operationId": "todayProjects", "responses": { "200": { "description": "Returns today's date, the total count of projects happening today, and a list of project names with their signed-up volunteers and any guests.", "content": { "application/json": { "schema": { "properties": { "date": { "description": "Today's date.", "type": "string", "example": "2025-11-15" }, "total_projects": { "description": "Number of projects happening today.", "type": "integer", "example": 2 }, "projects": { "description": "List of projects with volunteer rosters for today.", "type": "array", "items": { "properties": { "name": { "description": "Name of project.", "type": "string", "example": "Saturday Pantry Pack" }, "volunteer": { "description": "Signed-up volunteers for this project today.", "type": "array", "items": { "properties": { "full_name": { "type": "string", "example": "Priya Sharma" }, "display_name": { "type": "string", "example": "Priya Sharma +1" }, "guests": { "type": "array", "items": { "properties": { "full_name": { "type": "string", "example": "Priya Guest" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } }, "status": { "description": "Response status. Always 'OK' on success.", "type": "string", "example": "OK" } }, "type": "object" }, "example": { "date": "2025-11-15", "total_projects": 2, "projects": [ { "name": "Saturday Pantry Pack", "volunteer": [ { "full_name": "Priya Sharma", "display_name": "Priya Sharma +1", "guests": [ { "full_name": "Priya Guest" } ] }, { "full_name": "Aisha Mohamed", "display_name": "Aisha Mohamed", "guests": [] } ] }, { "name": "Neighborhood Cleanup Drive", "volunteer": [ { "full_name": "Marcus Castellano", "display_name": "Marcus Castellano +2", "guests": [ { "full_name": "Elena Castellano" }, { "full_name": "Marcus Guest" } ] } ] } ], "status": "OK" } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users": { "get": { "tags": [ "Users" ], "summary": "List / find Users", "description": "Returns a paginated list of users who are members of your organization. Use this endpoint to sync volunteer records into an external system, or to search for specific users by name or email before creating or updating them. Results are scoped to your organization — users in other organizations are not returned.", "operationId": "listUsers", "parameters": [ { "name": "page", "in": "query", "description": "Page number (if paging results).", "required": false, "schema": { "type": "integer" } }, { "name": "name_like", "in": "query", "description": "A name, or part of a name, to search for. This searches both the first and last name.", "required": false, "schema": { "type": "string" } }, { "name": "email_like", "in": "query", "description": "An email address, or part of an address, to search for.", "required": false, "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "description": "Date the User account was created on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_after", "in": "query", "description": "Date the User account was created on or after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "description": "Date the user was updated on or before.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Date the user was updated on or after", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Returns the paginated list of users who are members of your organization. The response includes pagination links and meta fields to navigate additional pages.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserResource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "example": { "data": [ { "type": "user", "id": "7903", "first_name": "Priya", "last_name": "Sharma", "full_name": "Priya Sharma", "email": "priya.sharma@example.org", "address": "123 Maple Ave, McKinney, TX 75069, USA", "phone": "(555) 012-0103", "birthday": "1990-03-15", "gender": "F", "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:22:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "ORGANIZER" }, { "type": "user", "id": "7821", "first_name": "Marcus", "last_name": "Castellano", "full_name": "Marcus Castellano", "email": "marcus.castellano@example.org", "address": "456 Oak Lane, McKinney, TX 75069, USA", "phone": "(555) 012-0101", "birthday": "1985-07-22", "gender": "M", "created_at": "2025-11-02T10:00:00+00:00", "updated_at": "2025-11-02T10:00:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "VOLUNTEER" }, { "type": "user", "id": "8104", "first_name": "Aisha", "last_name": "Mohamed", "full_name": "Aisha Mohamed", "email": "aisha.mohamed@example.org", "address": "789 Birch Dr, McKinney, TX 75069, USA", "phone": "(555) 012-0104", "birthday": "1993-11-08", "gender": "F", "created_at": "2025-11-03T11:00:00+00:00", "updated_at": "2025-11-03T11:00:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "VOLUNTEER" } ], "links": { "first": "https://api.vomo.org/v1/users?page=1", "last": "https://api.vomo.org/v1/users?page=2", "prev": null, "next": "https://api.vomo.org/v1/users?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 2, "to": 15, "path": "https://api.vomo.org/v1/users", "per_page": 15, "total": 22 } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Create / Update User", "description": "Upserts a user by email address. If no user with the given email exists, a new user is created and a 201 response is returned. If a user with that email already exists, their record is updated and a 200 response is returned. Note: if the user belongs to an organization other than your own organization or one of its child organizations, their core profile fields (name, email, password) cannot be modified — only their membership role within your organization can be adjusted.", "operationId": "createUser", "requestBody": { "description": "User to create / update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWriteRequest" } } } }, "responses": { "200": { "description": "A user with the provided email already existed and has been updated. Returns the updated user record.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "200" }, "message": { "type": "string", "example": "User updated." }, "data": { "$ref": "#/components/schemas/UserResource" } }, "type": "object" }, "example": { "code": "200", "message": "User updated.", "data": { "type": "user", "id": "8205", "first_name": "Tyler", "last_name": "Reyes", "full_name": "Tyler Reyes", "email": "tyler.reyes@example.org", "address": "321 Pine Rd, McKinney, TX 75069, USA", "phone": "(555) 012-0105", "birthday": "1995-06-30", "gender": "M", "created_at": "2025-11-04T08:00:00+00:00", "updated_at": "2025-11-19T10:15:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "VOLUNTEER", "participations": [], "profile_field_values": [] } } } } }, "201": { "description": "No user with the provided email existed; a new user has been created and added to your organization. Returns the newly created user record.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "201" }, "message": { "type": "string", "example": "User created." }, "data": { "$ref": "#/components/schemas/UserResource" } }, "type": "object" }, "example": { "code": "201", "message": "User created.", "data": { "type": "user", "id": "8311", "first_name": "Margaret", "last_name": "Williams", "full_name": "Margaret Williams", "email": "margaret.williams@example.org", "address": "654 Elm Ct, McKinney, TX 75069, USA", "phone": "(555) 012-0111", "birthday": "1975-12-01", "gender": "F", "created_at": "2025-11-20T13:00:00+00:00", "updated_at": "2025-11-20T13:00:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "VOLUNTEER", "participations": [], "profile_field_values": [] } } } } }, "400": { "description": "The organization slug or ID provided in the request does not match any organization in your family.", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The organization provided was not found." } }, "type": "object" } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "No API key provided" } } } } }, "422": { "description": "One or more request fields failed validation. This can occur from the request rules (e.g. missing email) or from the inline password requirement when creating a new user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "email": [ "The email field is required." ], "password": [ "The password field is required." ] } } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get User Details", "description": "Returns the full profile record for a single user who is a member of your organization, including their membership details and volunteer history metadata. The user must be a member of your organization; requests for users outside your organization return a 400 error.", "operationId": "getUserDetails", "parameters": [ { "name": "id", "in": "path", "description": "The unique VOMO identifier for the user to retrieve.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns the full user profile record for the specified member of your organization.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetailResource" } } }, "type": "object" }, "example": { "data": { "type": "user", "id": "7903", "first_name": "Priya", "last_name": "Sharma", "full_name": "Priya Sharma", "email": "priya.sharma@example.org", "address": "123 Maple Ave, McKinney, TX 75069, USA", "phone": "(555) 012-0103", "birthday": "1990-03-15", "gender": "F", "created_at": "2025-11-01T09:00:00+00:00", "updated_at": "2025-11-05T14:22:00+00:00", "user_status": "VERIFIED", "membership_status": "ACCEPTED", "membership_role": "ORGANIZER", "participations": [ { "guests": 1, "checked_in_at": "2025-11-15T09:04:00+00:00", "checked_out_at": "2025-11-15T12:01:00+00:00", "signed_up_at": "2025-11-10T14:00:00+00:00", "hours": "3.00", "verified": 1, "role": "Packer", "project_id": 4001, "project_date_id": 40001 } ], "profile_field_values": [] } } } } }, "400": { "description": "The requested user ID is not a member of your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 400, "message": "This user id does not represent a valid member of your organization." } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": 401, "message": "Invalid API key" } } } } }, "404": { "description": "No user exists with the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "No query results for model [App\\\\Models\\\\User]." } } } }, "429": { "description": "You have exceeded the rate limit of 30 requests per minute per API key.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Too Many Attempts." } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Server Error" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "PaginationLinks": { "description": "Pagination navigation links returned on every paginated list response. Each URL points at the specific list endpoint being called.", "properties": { "first": { "description": "A link to the first page of results", "type": "string" }, "last": { "description": "A link to the last page of results", "type": "string" }, "prev": { "description": "A link to the previous page of results, or null on the first page", "type": "string", "nullable": true }, "next": { "description": "A link to the next page of results, or null on the last page", "type": "string", "nullable": true } }, "type": "object" }, "Address": { "description": "An address in Google Maps API format.", "properties": { "lat": { "type": "number", "format": "float", "example": 33.214561 }, "lng": { "type": "number", "format": "float", "example": -96.614456 }, "country": { "type": "string", "example": "United States" }, "locality": { "type": "string", "example": "McKinney" }, "timezone": { "type": "string", "example": "America/Chicago" }, "postal_code": { "type": "string", "example": "75069" }, "country_short": { "type": "string", "example": "US" }, "locality_short": { "type": "string", "example": "McKinney" }, "formatted_address": { "type": "string", "example": "610 Elm St Suite 800, McKinney, TX 75069, USA" }, "postal_code_short": { "type": "string", "example": "75069" }, "administrative_area_level_1": { "type": "string", "example": "Texas" }, "administrative_area_level_1_short": { "type": "string", "example": "TX" } }, "type": "object" }, "PointPerson": { "description": "A contact person to meet on the day of the project. This contact info goes in the signup confirmation email, but this person does not receive notifications.", "properties": { "name": { "type": "string", "maximum": 255, "example": "John Volunteer", "nullable": true }, "phone": { "type": "string", "maximum": 45, "minimum": 10, "example": "5555555555", "nullable": true }, "email": { "type": "string", "maximum": 100, "minimum": 3, "example": "volunteer@vomo.org", "nullable": true } }, "type": "object" }, "RoleInput": { "description": "A volunteer role on a serving date.", "properties": { "id": { "description": "The ID of the role. When provided, will update an existing role. When not provided, will create a new role. If an existing role ID is omitted, that role will be deleted -- unless a volunteer with an active (non-denied, non-left) signup is assigned to it on an upcoming date, in which case the request will be rejected with a 422 and no changes will be saved.", "type": "string", "example": "123", "nullable": true }, "name": { "description": "The name of the role.", "type": "string", "example": "Greeter" }, "description": { "description": "The description for the role", "type": "string", "example": "A cheery person for greeting guests as they come in." }, "capacity": { "description": "The capacity for the role", "type": "integer", "example": 2 } }, "type": "object" }, "ItemInput": { "description": "An item needed on a serving date.", "properties": { "id": { "description": "The ID of the item. When provided, will update an existing item. When not provided, will create a new item. If an existing item ID is omitted, that item will be deleted -- unless a volunteer with an active (non-denied, non-left) signup is assigned to it on an upcoming date, in which case the request will be rejected with a 422 and no changes will be saved.", "type": "string", "example": "123", "nullable": true }, "name": { "description": "The name of the item that is needed", "type": "string", "example": "Bottled Water" }, "description": { "description": "The description for the item", "type": "string", "example": "A case of 24" }, "capacity": { "description": "The total number of items needed", "type": "integer", "example": 10 } }, "type": "object" }, "ProjectDateInput": { "description": "A serving date for a project.", "properties": { "id": { "description": "The ID of the serving date. Provide it to update an existing date; omit it to create a new date. Omitting an existing date does NOT delete it — a date is removed only when it is included in the request with status 'deleted'.", "type": "string", "example": "123", "nullable": true }, "starts_at": { "description": "That date and time the project will start. The time should be set to the project's timezone.", "type": "string", "example": "2020-01-01 09:00:00" }, "ends_at": { "description": "That date and time the project will end. The time should be set to the project's timezone.", "type": "string", "example": "2020-01-01 12:00:00" }, "status": { "description": "Default 'existing'. Set to 'deleted' to remove an existing date — see id property for full upsert semantics.", "type": "string", "enum": [ "existing", "deleted" ], "example": "existing", "nullable": true }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/RoleInput" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ItemInput" } } }, "type": "object" }, "OwnerInput": { "description": "A project owner assignment.", "properties": { "id": { "description": "The VOMO user ID of the person who should be assigned as an owner", "type": "integer", "example": 1 }, "is_primary_owner": { "description": "Whether or not this is a primary owner. There must be one primary owner per project.", "type": "boolean", "example": 1 }, "send_notifications": { "description": "Whether this owner should receive project notifications.", "type": "boolean", "example": 1 } }, "type": "object" }, "LinkInput": { "description": "A hyperlink to attach to a project.", "properties": { "title": { "type": "string", "example": "Go here for more information", "nullable": true }, "link": { "type": "string", "format": "uri", "maxLength": 255, "example": "https://vomo.org", "nullable": true } }, "type": "object" }, "AttachmentFileInput": { "description": "A file attachment to include on a project.", "required": [ "file", "filename" ], "properties": { "file": { "description": "A URL to the file", "type": "string" }, "filename": { "description": "The display name of the file", "type": "string" } }, "type": "object" }, "ImageInput": { "description": "A project image in multiple sizes.", "properties": { "l": { "description": "A large size of the image", "type": "string", "example": "https://assets.vomo.org/categories/animals/Animals.jpg" }, "s": { "description": "A small size of the image", "type": "string", "example": "https://assets.vomo.org/categories/animals/Animals+small.jpg" }, "o": { "description": "The original size of the image", "type": "string", "example": "https://assets.vomo.org/categories/animals/Animals.jpg" } }, "type": "object" }, "CategoryReference": { "description": "A reference to an existing category by ID.", "properties": { "id": { "type": "integer", "example": 1 } }, "type": "object" }, "CampaignReference": { "description": "A reference to an existing campaign by ID.", "properties": { "id": { "type": "integer", "example": 1 } }, "type": "object" }, "GroupMembersWriteRequest": { "description": "The complete set of user IDs that should make up the group's membership after the request.", "required": [ "members" ], "properties": { "members": { "description": "The VOMO user IDs that will become the group's complete membership. This replaces the existing members — any current member whose ID is omitted is removed. Each ID must correspond to a user who is a member of your organization.", "type": "array", "items": { "type": "integer", "example": "1" } } }, "type": "object" }, "PaginationMeta": { "description": "Pagination metadata returned on every paginated list response.", "properties": { "current_page": { "description": "The current page", "type": "integer", "example": "1" }, "from": { "description": "The index of the first result on this page", "type": "integer", "example": "1" }, "last_page": { "description": "The number of the last page of results", "type": "integer", "example": "4" }, "to": { "description": "The index of the last result on this page", "type": "integer", "example": "15" }, "path": { "description": "The base URL of the list endpoint", "type": "string" }, "per_page": { "description": "The number of results per page", "type": "integer", "example": "15" }, "total": { "description": "The total number of results", "type": "integer", "example": "49" } }, "type": "object" }, "ApiError": { "description": "Error response returned for authentication failures (401) and business-rule violations (400). The error detail is nested under the 'error' key. Always send the 'Accept: application/json' request header — without it, some error responses (notably 404, 422, 429, and 500) may be returned as HTML instead of JSON.", "required": [ "error" ], "properties": { "error": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "No API key provided" } }, "type": "object" } }, "type": "object" }, "ValidationError": { "description": "Error response returned when one or more request fields fail validation (HTTP 422). The 'message' field summarises the failure; 'errors' maps each invalid field name to an array of human-readable error strings.", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "description": "A map of field name to an array of validation error messages for that field.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "example": "The name field is required." } } } }, "type": "object" }, "MessageResponse": { "description": "Simple message-only error response returned by the framework for 403 (unauthorized), 404 (not found), 429 (rate limit), and 500 (server error) responses.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "type": "object" }, "UserWriteRequest": { "description": "Request body for creating or updating a user.", "required": [ "first_name", "last_name", "birthday", "email", "gender" ], "properties": { "first_name": { "description": "The first name of the user", "type": "string", "example": "John" }, "last_name": { "description": "The last name of the user", "type": "string", "example": "Doe" }, "email": { "description": "The email for the user", "type": "string", "example": "john.doe@example.com" }, "password": { "description": "The user's password. Must be at least 10 characters and include letters and numbers.", "type": "string", "minimum": 10, "example": "password1234" }, "org": { "description": "Optional. The slug of the organization to assign the user to. Defaults to your partner organization. Must be your own organization or one of its child organizations.", "type": "string", "example": "vomo" }, "invite_code": { "description": "Optional. The invitation code for the target organization. When supplied, this takes precedence over the org field and determines which organization the user is added to.", "type": "string", "example": "vomoinvitationcode" }, "birthday": { "description": "The birthday for the user", "type": "string", "format": "YYYY-MM-DD", "example": "1975-12-01" }, "gender": { "description": "The gender for the user", "type": "string", "enum": [ "M", "F", "N" ], "example": "M" }, "phone": { "description": "Optional. The phone number for the user.", "type": "string", "example": "555-867-5309" }, "role": { "description": "Optional. The user's role within your organization. Defaults to VOLUNTEER when not provided. Possible values: `VOLUNTEER` — standard volunteer member; `ORGANIZER` — can create and manage projects and events; `ADMIN` — organization administrator with full management access.", "type": "string", "enum": [ "VOLUNTEER", "ORGANIZER", "ADMIN" ], "example": "VOLUNTEER" } }, "type": "object" }, "GroupWriteRequest": { "description": "Request body for creating or updating a group.", "required": [ "name" ], "properties": { "name": { "description": "The name of the group", "type": "string", "maximum": 255, "minimum": 4, "example": "Morning Crew" }, "description": { "description": "A description for the group", "type": "string", "maximum": 500, "example": "A group for the morning crew to organize", "nullable": true }, "member_moniker": { "description": "A word describing a group member", "type": "string", "maximum": 2000, "minimum": 3, "example": "Member" }, "subgroup_moniker": { "description": "A word describing subgroups", "type": "string", "maximum": 2000, "minimum": 3, "example": "Subgroup" }, "created_by_user_id": { "description": "Optional. If provided, must be an existing user who is a member of the organization.", "type": "integer", "example": "1" }, "parent_id": { "description": "The VOMO Group ID to set as the parent group of the newly created group", "type": "integer", "example": "1" }, "members": { "description": "User IDs to set as the group's membership. On create (POST), these become the initial members. On update (PUT), this **replaces** the existing membership — any current member omitted from the array is removed from the group. Pass an empty array to clear all members.", "type": "array", "items": { "type": "integer", "example": "1" } } }, "type": "object" }, "OrganizationWriteRequest": { "description": "Request body for creating an organization.", "required": [ "name", "description", "org_size", "email", "type", "address" ], "properties": { "name": { "description": "The name of the organization", "type": "string", "maximum": 255, "minimum": 3, "example": "Help the Hungry" }, "description": { "description": "A description of the organization", "type": "string", "maximum": 500, "minimum": 3, "example": "A nonprofit dedicated to eliminating food insecurity in our community." }, "org_size": { "description": "The number of people in the organization", "type": "integer", "minimum": 0, "example": 250 }, "email": { "description": "The primary contact email for the organization", "type": "string", "format": "email", "example": "admin@helpthehungry.org" }, "type": { "description": "The organization type. Possible values: `NPO` — Non-profit organization; `BIZ` — Business; `FCO` — Faith-based organization; `GOV` — Governmental; `EDU` — Educational institution.", "type": "string", "enum": [ "NPO", "BIZ", "FCO", "GOV", "EDU" ], "example": "NPO" }, "address": { "description": "The address of the organization in Google Maps API format. All address fields are required when creating an organization.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "mission_statement": { "description": "The mission statement for the organization", "type": "string", "example": "To end hunger one meal at a time.", "nullable": true }, "website": { "description": "The website URL for the organization", "type": "string", "example": "https://helpthehungry.org", "nullable": true }, "phone": { "description": "The primary phone number for the organization", "type": "string", "maximum": 45, "minimum": 10, "example": "5551234567", "nullable": true } }, "type": "object" }, "ProjectWriteRequest": { "description": "Request body for creating or updating a project.", "required": [ "name", "description", "allow_guests", "age_limit", "address", "privacy", "participant_approval_required", "show_volunteer_counter", "volunteer_counter_threshold", "owners" ], "properties": { "name": { "description": "The name of the project", "type": "string", "maximum": 255, "minimum": 3, "example": "Community Gathering" }, "description": { "description": "A description for the project", "type": "string", "maximum": 2000, "minimum": 3, "example": "Inviting & meeting new neighbors of the community. Serving meals, setup game stations, face paintings for kids...etc." }, "details": { "description": "Emphasize important details such as shoes to wear or items to bring. This information goes in the signup confirmation email, and is a great place to detail next steps in a Project", "type": "string", "maximum": 1000, "example": "Wear comfortable shoes!" }, "allow_guests": { "description": "Whether to allow volunteers to bring guests", "type": "boolean", "default": 0, "example": 1 }, "age_limit": { "description": "The minimum age a volunteer must be", "type": "integer", "maximum": 99, "minimum": 0, "example": 13 }, "volunteer_question": { "description": "Ask your volunteers to provide additional information about themselves as they register. This field will be required to join the Serving Date.", "type": "string", "maximum": 500, "example": "What is your t-shirt size?" }, "participant_approval_required": { "description": "Volunteers must be approved by the organizer before their spot is reserved.", "type": "boolean", "default": 0, "example": 1 }, "background_check_required": { "description": "Volunteers must have a background check before signing up for your Project.", "type": "boolean", "default": 0, "example": 1 }, "show_volunteer_counter": { "description": "Display number of participants. Note that this will only show on the project page if it is an Anytime project", "type": "boolean", "default": 0, "example": 1 }, "volunteer_counter_threshold": { "description": "The minimum number of volunteers signed up before the counter is shown. Note that this will only show on the project page if it is an Anytime project", "type": "integer", "maximum": 999999, "minimum": 0, "example": 10 }, "draft": { "description": "When a project is in draft, it will not be viewable by anyone.", "type": "boolean", "default": 0, "example": 0 }, "privacy": { "description": "The visibility of the project. Possible values: `PUBLIC` — accessible by all VOMO users; `PRIVATE` — accessible only by members of the organization (those in the People list); `UNLISTED` — not listed publicly but accessible via direct link.", "type": "string", "enum": [ "PUBLIC", "PRIVATE", "UNLISTED" ], "example": "PUBLIC" }, "organization_id": { "description": "The Organization ID to post the project to. Note, you must be part of the organization to post a project to it.", "type": "integer", "example": 1 }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageInput" } }, "point_person": { "description": "Identify a person to contact or meet on the day of the Project. This contact info goes in the signup confirmation email, but this person does not receive notifications.", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PointPerson" } ] }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryReference" } }, "campaigns": { "description": "A list of existing campaigns to associate with the project. For organizations without a hub experience, at least one campaign is required; otherwise this is optional.", "type": "array", "items": { "$ref": "#/components/schemas/CampaignReference" } }, "attachment_files": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentFileInput" } }, "owners": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerInput" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/LinkInput" } }, "address": { "description": "The address where the project will take place. The format used is the standard Google address API. Only `timezone` is required; all other fields are optional.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "project_type": { "description": "The scheduling type for the project. Cannot be changed after a project has been created. Possible values: `dated` — the project has specific dates and times when volunteers are needed; `anytime` — volunteers can participate at any time, with no fixed schedule.", "type": "string", "enum": [ "dated", "anytime" ], "example": "dated" }, "dates": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectDateInput" } } }, "type": "object" }, "CampaignDetailResource": { "description": "A VOMO Campaign with full project details", "properties": { "type": { "description": "The VOMO object type", "type": "string", "example": "campaign" }, "campaign_id": { "description": "The VOMO campaign ID (cast to string)", "type": "string", "example": "1" }, "campaign_name": { "description": "The name of the campaign", "type": "string", "example": "Together" }, "description": { "description": "The description for the campaign", "type": "string", "example": "Example description.", "nullable": true }, "url": { "description": "A URL to the campaign on VOMO", "type": "string", "example": "http://app.vomo.org/initiative/together" }, "organization": { "description": "The organization name the campaign belongs to", "type": "string", "example": "VOMO" }, "organization_slug": { "description": "The organization slug the campaign belongs to", "type": "string", "example": "vomo" }, "organization_id": { "description": "The organization ID the campaign belongs to", "type": "integer", "example": 1 }, "author_id": { "description": "The VOMO user ID of the person who created the campaign", "type": "integer", "example": 1, "nullable": true }, "logo_url": { "description": "The URL for the campaign logo image", "type": "string", "example": "https://s3.amazonaws.com/awakenmycity/j2/7Z/r4-s.jpg", "nullable": true }, "created_at": { "description": "The date and time the campaign was created", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "updated_at": { "description": "The date and time the campaign was last updated", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "projects": { "description": "The full project detail records associated with this campaign.", "type": "array", "items": { "$ref": "#/components/schemas/ProjectDetailResource" } } }, "type": "object" }, "CampaignResource": { "description": "A VOMO Campaign", "properties": { "type": { "description": "The VOMO object type", "type": "string", "example": "campaign" }, "id": { "description": "The VOMO campaign ID (cast to string)", "type": "string", "example": "1" }, "campaign_name": { "description": "The name of the campaign", "type": "string", "example": "Together" }, "description": { "description": "The description for the campaign", "type": "string", "example": "Example description." }, "url": { "description": "A URL to the campaign on VOMO", "type": "string", "example": "http://app.vomo.org/initiative/together" }, "organization": { "description": "The organization name the campaign is in", "type": "string", "example": "VOMO" }, "organization_id": { "description": "The Organization ID the campaign belongs to.", "type": "integer", "example": 1, "nullable": true }, "organization_slug": { "description": "The organization slug the campaign is in", "type": "string", "example": "vomo", "nullable": true }, "author_id": { "description": "The VOMO user ID of the person who created the campaign", "type": "integer", "example": "1" }, "logo_url": { "description": "The URL for the campaign logo image", "type": "string", "example": "https://s3.amazonaws.com/awakenmycity/j2/7Z/r4-s.jpg" }, "updated_at": { "description": "The date and time the campaign was updated at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "created_at": { "description": "The date and time the campaign was created at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" } }, "type": "object" }, "CertificateResource": { "description": "A VOMO Certification", "properties": { "id": { "description": "The ID of the certification", "type": "integer", "example": 1 }, "name": { "description": "The name of the certification", "type": "string", "example": "Volunteer Application" }, "requirement": { "description": "A description / requirement for the certification", "type": "string", "example": "Watch tutorial videos.", "nullable": true }, "slug": { "description": "The slug for the certification", "type": "string", "example": "2d8614a5-31ed-4810-8da2-448f59463e43" }, "expiration_in_months": { "description": "The certification default expiration after completion in months", "type": "integer", "example": 12, "nullable": true }, "creator_id": { "description": "The ID of the certification creator", "type": "integer", "example": 1, "nullable": true }, "organization_id": { "description": "The ID of the organization the certification belongs to", "type": "integer", "example": 1, "nullable": true }, "created_at": { "description": "The date and time the certification was created at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "updated_at": { "description": "The date and time the certification was last updated at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" } }, "type": "object" }, "FormCompletionResource": { "description": "List of Form Completions", "properties": { "type": { "description": "The type of VOMO Object", "type": "string", "example": "form_completion" }, "id": { "description": "The ID of the form completion", "type": "integer", "example": "1" }, "form_id": { "description": "The ID of the form", "type": "integer", "example": "1" }, "user_id": { "description": "The ID of the user who completed the form", "type": "integer", "example": "1" }, "project_id": { "description": "The ID of the project this form submission is associated with", "type": "integer", "example": 1, "nullable": true }, "participation_id": { "description": "The ID of the participation this form submission is associated with", "type": "integer", "example": 1, "nullable": true }, "updated_at": { "description": "The date and time the form completion was updated at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "created_at": { "description": "The date and time the form completion was created at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "field_responses": { "description": "The form field responses", "type": "array", "items": { "$ref": "#/components/schemas/FormFieldResponseResource" } } }, "type": "object" }, "FormFieldOptionResource": { "description": "A VOMO Form Field Option", "properties": { "type": { "description": "The type of VOMO Object", "type": "string", "example": "field_option" }, "id": { "description": "The ID of the option", "type": "integer", "example": 1 }, "name": { "description": "The display name of the option", "type": "string", "example": "Small" }, "value": { "description": "The stored value of the option", "type": "string", "example": "S" }, "enabled": { "description": "Whether the option is enabled and selectable", "type": "boolean", "example": true }, "weight": { "description": "The sort order position of the option in its list", "type": "integer", "example": 0 } }, "type": "object" }, "FormFieldResource": { "description": "A VOMO Form Field", "properties": { "type": { "description": "The type of VOMO Object", "type": "string", "example": "form_field" }, "id": { "description": "The ID of the field. This is the same identifier returned as `field_id` on a form field response, so it can be used to correlate a form definition with the answers submitted against it.", "type": "integer", "example": 1 }, "name": { "description": "The name of the field", "type": "string", "example": "T-shirt Size" }, "description": { "description": "The description of the field", "type": "string", "example": "Please select a T-Shirt size", "nullable": true }, "field_type": { "description": "The type of input for this field. General types: `SHORTTEXT` — single-line text answer; `LONGTEXT` — multi-line text answer; `DROPDOWN` — single selection from a list of options; `MULTIPLESELECT` — multiple selections from a list of options; `WAIVER` — a waiver or agreement the volunteer must accept; `TEXTSINGLE` — a single informational text block (no input); `GROUP` — assigns the volunteer to one or more groups; `DOCUMENTUPLOAD` — file upload field. The `VIRTUOUSPAYMENTS-*` types appear only on giving forms: `VIRTUOUSPAYMENTS-AMOUNT` — donation amount selector; `VIRTUOUSPAYMENTS-DONORPAYSCOSTS` — option for the donor to cover processing fees; `VIRTUOUSPAYMENTS-RECURRING` — recurring donation frequency selector; `VIRTUOUSPAYMENTS-PAYMENTINFORMATION` — payment card input; `VIRTUOUSPAYMENTS-BILLINGINFORMATION` — billing address input; `VIRTUOUSPAYMENTS-NAME` — donor name input; `VIRTUOUSPAYMENTS-EMAIL` — donor email input.", "type": "string", "enum": [ "SHORTTEXT", "LONGTEXT", "DROPDOWN", "MULTIPLESELECT", "WAIVER", "TEXTSINGLE", "GROUP", "DOCUMENTUPLOAD", "VIRTUOUSPAYMENTS-AMOUNT", "VIRTUOUSPAYMENTS-DONORPAYSCOSTS", "VIRTUOUSPAYMENTS-RECURRING", "VIRTUOUSPAYMENTS-PAYMENTINFORMATION", "VIRTUOUSPAYMENTS-BILLINGINFORMATION", "VIRTUOUSPAYMENTS-NAME", "VIRTUOUSPAYMENTS-EMAIL" ], "example": "DROPDOWN" }, "slug": { "description": "The unique slug for the field", "type": "string", "example": "2d8614a5-31ed-4810-8da2-448f59463e43" }, "show_in_profile": { "description": "Whether the field should appear in the user's profile", "type": "boolean", "example": true }, "options": { "description": "The field options, when applicable", "type": "array", "items": { "$ref": "#/components/schemas/FormFieldOptionResource" } } }, "type": "object" }, "FormFieldResponseResource": { "description": "Form Field Response", "properties": { "type": { "description": "The type of VOMO Object", "type": "string", "example": "form_field_response" }, "id": { "description": "The ID of the response", "type": "integer", "example": "1" }, "form_completion_id": { "description": "The ID of the form completion", "type": "integer", "example": "1" }, "user_id": { "description": "The ID of the user who completed the form field", "type": "integer", "example": "1" }, "field_id": { "description": "The ID of the form field", "type": "integer", "example": "1" }, "value": { "description": "The raw answer value for this field response. What this contains varies by field type: SHORTTEXT and LONGTEXT — the text the volunteer entered; DROPDOWN — the name of the selected option; GROUP — a JSON array of group IDs the volunteer was assigned to; DOCUMENTUPLOAD — the identifier of the uploaded file; WAIVER — the acceptance string; MULTIPLESELECT — not currently populated (selections for multiple-select fields are stored separately and are not returned in this field).", "type": "string", "example": "S", "nullable": true } }, "type": "object" }, "FormResource": { "description": "A VOMO Form", "properties": { "type": { "description": "The type of VOMO Object", "type": "string", "example": "form" }, "id": { "description": "The ID of the form", "type": "integer", "example": 1 }, "name": { "description": "The name of the form", "type": "string", "example": "Volunteer Application" }, "form_type": { "description": "The form type. Possible values: `PROJECT` — a form attached to a specific project or serving opportunity; `REGISTRATION` — an organization-level registration or onboarding form; `KIOSK` — a self-serve check-in form used on a shared device at a volunteer site; `GIVING` — a giving or donation form.", "type": "string", "enum": [ "PROJECT", "REGISTRATION", "KIOSK", "GIVING" ], "example": "PROJECT" }, "slug": { "description": "The unique slug for the form", "type": "string", "example": "2d8614a5-31ed-4810-8da2-448f59463e43" }, "description": { "description": "A description for the form", "type": "string", "example": "Thank you for supporting our organization. This is a standard application required for volunteering with us.", "nullable": true }, "author_id": { "description": "The ID of the form author", "type": "integer", "example": 1, "nullable": true }, "organization_id": { "description": "The ID of the organization the form belongs to", "type": "integer", "example": 1, "nullable": true }, "created_at": { "description": "The date and time the form was created at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "updated_at": { "description": "The date and time the form was last updated at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "deleted_at": { "description": "The date and time the form was archived at. Null if not archived.", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00", "nullable": true }, "fields": { "description": "The form fields", "type": "array", "items": { "$ref": "#/components/schemas/FormFieldResource" } } }, "type": "object" }, "GroupResource": { "description": "List of Groups", "properties": { "id": { "description": "The ID of the group", "type": "integer", "example": "1" }, "name": { "description": "The name of the group", "type": "string", "maximum": 45, "minimum": 3, "example": "Afternoon Team" }, "description": { "description": "A description for the group", "type": "string", "example": "This team will take over for the morning team at 12pm" }, "has_subgroups": { "description": "If the group has subgroups", "type": "boolean", "example": true }, "parent_id": { "description": "The group ID of the parent group", "type": "integer", "example": "1" }, "subgroups": { "description": "Child subgroups of this group. Present only when the 'children' relation is loaded (e.g. on detail endpoints).", "type": "array", "items": { "$ref": "#/components/schemas/GroupResource" } }, "parent": { "description": "The parent group of this group. Present only when the 'parent' relation is loaded (e.g. on detail endpoints).", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/GroupResource" } ] }, "created_at": { "description": "The date and time the group was created at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "updated_at": { "description": "The date and time the group was last updated at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" } }, "type": "object" }, "HappeningResource": { "description": "A VOMO Happening", "properties": { "type": { "description": "The type of VOMO object", "type": "string", "example": "project_date" }, "id": { "description": "Project Date ID", "type": "integer", "example": "1" }, "starts_at": { "description": "The date and time when a Project Date will start", "type": "string", "format": "date-time", "example": "2020-01-01T12:00:00+00:00" }, "ends_at": { "description": "The date and time when a Project Date will end", "type": "string", "format": "date-time", "example": "2020-01-01T19:00:00+00:00" }, "participant_count": { "description": "The total number of confirmed participants for this date", "type": "integer", "example": 13 } }, "type": "object" }, "OrganizationResource": { "description": "A VOMO Organization", "properties": { "id": { "description": "The unique VOMO ID for the organization", "type": "integer", "example": 12345 }, "name": { "description": "The name of the organization", "type": "string", "example": "VOMO Org" }, "slug": { "description": "The unique URL slug for the organization", "type": "string", "example": "vomo" }, "type": { "description": "The organization type. Possible values: `NPO` — Non-profit organization; `BIZ` — Business; `FCO` — Faith-based organization; `GOV` — Governmental; `EDU` — Educational institution.", "type": "string", "enum": [ "NPO", "BIZ", "FCO", "GOV", "EDU" ], "example": "NPO" }, "description": { "description": "A description of the organization", "type": "string", "example": "A nonprofit dedicated to eliminating food insecurity.", "nullable": true }, "email": { "description": "The primary contact email for the organization", "type": "string", "example": "admin@vomo.org", "nullable": true }, "phone": { "description": "The primary phone number for the organization", "type": "string", "example": "123-456-7890", "nullable": true }, "website": { "description": "The website URL for the organization", "type": "string", "example": "https://vomo.org", "nullable": true }, "tax_number": { "description": "The tax identification number for the organization", "type": "string", "example": "12-3456789", "nullable": true }, "org_size": { "description": "The approximate number of people in the organization", "type": "integer", "example": 500, "nullable": true }, "background_check_expiration": { "description": "The background check expiration window. Possible values: `1_YEAR` — expires 1 year after the check date; `2_YEARS` — expires 2 years after; `3_YEARS` — expires 3 years after; `4_YEARS` — expires 4 years after; `5_YEARS` — expires 5 years after; `ABSOLUTE` — expires on the fixed calendar date set in background_check_absolute_expiration.", "type": "string", "enum": [ "1_YEAR", "2_YEARS", "3_YEARS", "4_YEARS", "5_YEARS", "ABSOLUTE" ], "example": "1_YEAR", "nullable": true }, "background_check_expiration_mode": { "description": "The background check expiration mode. Possible values: `relative` — background checks expire a fixed window after the check date (see background_check_expiration); `absolute` — all background checks expire on the fixed calendar date in background_check_absolute_expiration.", "type": "string", "enum": [ "relative", "absolute" ], "example": "relative", "nullable": true }, "background_check_absolute_expiration": { "description": "The fixed calendar date on which background checks expire when background_check_expiration_mode is 'absolute'.", "type": "string", "example": "2025-12-31", "nullable": true }, "invitation_token": { "description": "The invitation token for joining the organization", "type": "string", "example": "VOMO", "nullable": true }, "address": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "groups_moniker": { "description": "The display label used for groups in this organization", "type": "string", "example": "Group", "nullable": true }, "giving_enabled": { "description": "Whether giving/donations are enabled for this organization", "type": "boolean", "example": false, "nullable": true }, "created_at": { "description": "The date and time the organization was created", "type": "string", "example": "2019-02-01 17:33:39" }, "updated_at": { "description": "The date and time the organization was last updated", "type": "string", "example": "2019-05-31 19:31:43" }, "deleted_at": { "description": "The date and time the organization was deleted, or null if active", "type": "string", "example": null, "nullable": true }, "show_categories": { "description": "Whether to show category filters on the organization hub", "type": "integer", "example": 1 }, "show_rewards": { "description": "Whether to show the rewards/points feature for this organization", "type": "integer", "example": 0 }, "project_moniker": { "description": "The display label used for projects/opportunities in this organization", "type": "string", "example": "Project", "nullable": true }, "campaign_moniker": { "description": "The display label used for campaigns/initiatives in this organization", "type": "string", "example": "Campaign", "nullable": true }, "user_submitted_projects": { "description": "Whether volunteers can submit their own projects (0=no, 1=yes)", "type": "integer", "example": 0 }, "logo": { "description": "The organization logo media object, or null if no logo is set", "properties": { "id": { "type": "integer", "example": 99908 }, "type": { "type": "string", "example": "LOGO" }, "urls": { "properties": { "l": { "description": "Large image URL", "type": "string" }, "o": { "description": "Original image URL", "type": "string" }, "s": { "description": "Small image URL", "type": "string" } }, "type": "object" }, "flags": { "type": "string", "nullable": true }, "mediable_id": { "type": "integer", "example": 12345 }, "mediable_type": { "type": "string", "example": "organization" }, "created_at": { "type": "string", "example": "2019-03-28 15:37:09" }, "updated_at": { "type": "string", "example": "2019-03-28 15:37:14" }, "deleted_at": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "child_organizations": { "description": "Child organizations of this organization. Present only when the 'childOrganizations' relation is loaded (e.g. on show/store endpoints).", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResource" } }, "parent_organizations": { "description": "Parent organizations of this organization. Present only when the 'parentOrganizations' relation is loaded (e.g. on show/store endpoints).", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResource" } } }, "type": "object" }, "ParticipationResource": { "description": "A VOMO volunteer participation record", "properties": { "guests": { "description": "The number of guests for this participation", "type": "integer", "example": "1" }, "checked_in_at": { "description": "The date and time a user checked in for this participation", "type": "string", "format": "date-time", "example": "2020-01-01T12:00:00+00:00" }, "checked_out_at": { "description": "The date and time a user checked out of this participation", "type": "string", "format": "date-time", "example": "2020-01-01T12:00:00+00:00" }, "signed_up_at": { "description": "The date and time a user signed up for this participation", "type": "string", "format": "date-time", "example": "2020-01-01T12:00:00+00:00" }, "hours": { "description": "The calculated number of hours for the participation, returned as a decimal string (e.g. '2.00').", "type": "string", "example": "2.00" }, "verified": { "description": "If the participation has been verified by the organizer", "type": "boolean", "example": "1" }, "role": { "description": "The participants assigned role", "type": "string", "example": "Volunteer" }, "project_id": { "description": "The project ID associated with this participation", "type": "integer", "example": 1 }, "project_date_id": { "description": "The project date ID (happening ID) associated with this participation", "type": "integer", "example": 1 } }, "type": "object" }, "ProjectDateResource": { "description": "A VOMO Project Serving Date with participants", "properties": { "type": { "description": "The VOMO object type", "type": "string", "example": "project_date" }, "id": { "description": "The serving date (happening) ID, cast to string", "type": "string", "example": "5678" }, "project_name": { "description": "The name of the project this serving date belongs to", "type": "string", "example": "Volunteer Project" }, "starts_at": { "description": "The date and time the serving date starts", "type": "string", "format": "date-time", "example": "2020-01-01T12:00:00+00:00" }, "ends_at": { "description": "The date and time the serving date ends", "type": "string", "format": "date-time", "example": "2020-01-01T14:00:00+00:00" }, "participant_count": { "description": "The total number of confirmed participants (excluding denied/left) for this serving date", "type": "integer", "example": 20 }, "participants": { "description": "The list of participants (non-guest records only) for this serving date", "type": "array", "items": { "properties": { "type": { "description": "The VOMO object type", "type": "string", "example": "user" }, "id": { "description": "The participant's VOMO user ID", "type": "integer", "example": 123456 }, "email": { "description": "The participant's email address", "type": "string", "example": "user@vomo.org" }, "guests": { "description": "The number of guests this participant is bringing", "type": "integer", "example": 2 }, "checked_in_at": { "description": "The date and time the participant checked in, or null if not checked in", "type": "string", "format": "date-time", "example": "2020-01-01T12:00:00+00:00", "nullable": true }, "checked_out_at": { "description": "The date and time the participant checked out, or null if not checked out", "type": "string", "format": "date-time", "example": "2020-01-01T14:00:00+00:00", "nullable": true }, "signed_up_at": { "description": "The date and time the participant signed up", "type": "string", "format": "date-time", "example": "2020-01-01T12:00:00+00:00" }, "hours": { "description": "The calculated volunteer hours for this participation, as a decimal string", "type": "string", "example": "4.00" }, "verified": { "description": "Whether the participation has been verified by an organizer", "type": "boolean", "example": false }, "role": { "description": "The participant's assigned role name", "type": "string", "example": "Volunteer" }, "project_id": { "description": "The ID of the project", "type": "integer", "example": 1234 }, "project_date_id": { "description": "The ID of this serving date", "type": "integer", "example": 5678 }, "form_completions": { "description": "Form completions associated with this participation", "type": "array", "items": { "$ref": "#/components/schemas/FormCompletionResource" } } }, "type": "object" } } }, "type": "object" }, "ProjectDetailResource": { "description": "A VOMO Project", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProjectResource" }, { "properties": { "point_person": { "description": "Identify a person to contact or meet on the day of the Project. This contact info goes in the signup confirmation email, but this person does not receive notifications.", "properties": { "name": { "type": "string", "maximum": 255, "example": "John Volunteer" }, "phone": { "type": "string", "maximum": 45, "minimum": 10, "example": "5555555555" }, "email": { "type": "string", "maximum": 100, "minimum": 3, "example": "volunteer@vomo.org" } }, "type": "object" }, "allow_guests": { "description": "Whether to allow volunteers to bring guests", "type": "boolean", "default": 0, "example": 1 }, "age_limit": { "description": "The minimum age a volunteer must be", "type": "integer", "maximum": 99, "minimum": 0, "example": 13 }, "volunteer_question": { "description": "Ask your volunteers to provide additional information about themselves as they register. This field will be required to join the Serving Date.", "type": "string", "maximum": 500, "example": "What is your t-shirt size?" }, "participant_approval_required": { "description": "Volunteers must be approved by the organizer before their spot is reserved.", "type": "boolean", "default": 0, "example": 1 }, "background_check_required": { "description": "Volunteers must have a background check before signing up for your Project.", "type": "boolean", "default": 0, "example": 1 }, "show_volunteer_counter": { "description": "Display number of participants. Note that this will only show on the project page if it is an Anytime project", "type": "boolean", "default": 0, "example": 1 }, "volunteer_counter_threshold": { "description": "The minimum number of volunteers signed up before the counter is shown. Note that this will only show on the project page if it is an Anytime project", "type": "integer", "maximum": 99, "minimum": 0, "example": 10 }, "privacy": { "description": "The visibility of the project. Possible values: `PUBLIC` — accessible by all VOMO users; `PRIVATE` — accessible only by members of the organization (those in the People list); `UNLISTED` — not listed publicly but accessible via direct link.", "type": "string", "enum": [ "PUBLIC", "PRIVATE", "UNLISTED" ], "example": "PUBLIC" }, "all_dates": { "description": "All serving dates for the project. Present only when the 'happenings' relation is loaded.", "type": "array", "items": { "$ref": "#/components/schemas/HappeningResource" } } }, "type": "object" } ] }, "ProjectResource": { "description": "A VOMO Project", "properties": { "type": { "description": "The VOMO object type", "type": "string", "example": "project" }, "id": { "description": "The VOMO project id (cast to string)", "type": "string", "example": "1" }, "project_name": { "description": "The name of the project", "type": "string", "maximum": 255, "minimum": 3, "example": "Community Gathering" }, "description": { "description": "A description for the project", "type": "string", "maximum": 2000, "minimum": 3, "example": "Inviting & meeting new neighbors of the community. Serving meals, setup game stations, face paintings for kids...etc." }, "details": { "description": "Additional details for volunteers, included in the signup confirmation email.", "type": "string", "example": "Wear comfortable shoes!", "nullable": true }, "url": { "description": "A URL to the project", "type": "string", "example": "https://app.vomo.org/opportunity/generated-slug" }, "organization_id": { "description": "The Organization ID the project belongs to.", "type": "integer", "example": 1 }, "organization": { "description": "The Organization name the project belongs to.", "type": "string", "example": "VOMO" }, "organization_slug": { "description": "The Organization slug the project belongs to.", "type": "string", "example": "vomo" }, "author_id": { "description": "The VOMO user ID of the person who created the project.", "type": "integer", "example": 1, "nullable": true }, "owners": { "type": "array", "items": { "properties": { "id": { "description": "The VOMO user ID of the person who is an owner", "type": "integer", "example": 1 }, "is_primary_owner": { "description": "Whether or not this is a primary owner. There must be one primary owner per project.", "type": "boolean", "example": true }, "send_notifications": { "description": "Whether this owner should receive project notifications.", "type": "boolean", "example": true } }, "type": "object" } }, "address": { "description": "The address where the project will take place, in Google Maps API format.", "properties": { "lat": { "type": "string", "example": "40.70387040000001" }, "lng": { "type": "string", "example": "-74.0138541" }, "country": { "type": "string", "example": "United States" }, "locality": { "type": "string", "example": "BOWLING GREEN" }, "timezone": { "type": "string", "example": "America/New_York" }, "postal_code": { "type": "string", "example": "10004" }, "country_short": { "type": "string", "example": "US" }, "locality_short": { "type": "string", "example": "BOWLING GREEN" }, "formatted_address": { "type": "string", "example": "BOWLING GREEN, NY 10004, USA" }, "postal_code_short": { "type": "string", "example": "10004" }, "administrative_area_level_1": { "type": "string", "example": "New York" }, "administrative_area_level_1_short": { "type": "string", "example": "NY" } }, "type": "object", "nullable": true }, "anytime": { "description": "Whether the project is an anytime (open-ended) project with no specific serving dates.", "type": "boolean", "example": false }, "anywhere": { "description": "Whether the project can be done anywhere (no fixed location).", "type": "boolean", "example": false, "nullable": true }, "draft": { "description": "When true, the project is in draft mode and not publicly viewable.", "type": "boolean", "example": false }, "created_at": { "description": "The date and time the project was created at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "updated_at": { "description": "The date and time the project was updated at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "published_at": { "description": "The date and time the project was published. Empty string if not yet published.", "type": "string", "example": "2016-03-07T07:49:41+00:00" }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignResource" } }, "certificates": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateResource" } }, "form_completions": { "type": "array", "items": { "$ref": "#/components/schemas/FormCompletionResource" } }, "next_date": { "description": "The next upcoming serving date for the project.", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/HappeningResource" } ] }, "images": { "description": "An array of project image URLs (large size).", "type": "array", "items": { "type": "string", "example": "https://vomo-cdn.com/media/2019/01/01-sulmLi2Z-l.jpg" } } }, "type": "object" }, "UserDetailResource": { "description": "A VOMO User with full detail (participations and profile field values)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserResource" }, { "properties": { "participations": { "type": "array", "items": { "$ref": "#/components/schemas/ParticipationResource" } }, "profile_field_values": { "type": "array", "items": { "$ref": "#/components/schemas/FormFieldResponseResource" } } }, "type": "object" } ] }, "UserResource": { "description": "VOMO User", "properties": { "type": { "description": "VOMO object type", "type": "string", "example": "user" }, "id": { "description": "User's ID (cast to string)", "type": "string", "example": "1" }, "first_name": { "description": "User's First Name", "type": "string", "maximum": 45, "minimum": 3, "example": "John" }, "last_name": { "description": "User's Last Name", "type": "string", "example": "Doe" }, "full_name": { "description": "User's full name", "type": "string", "example": "John Doe" }, "email": { "description": "User's Email", "type": "string", "example": "person@vomo.org" }, "address": { "description": "User's Address", "type": "string", "example": "610 Elm St, McKinney, TX 75069, USA" }, "phone": { "description": "User's Phone Number", "type": "string", "example": "1234567890" }, "birthday": { "description": "The birthday for the user", "type": "string", "format": "YYYY-MM-DD", "example": "1975-12-01" }, "gender": { "description": "The gender for the user. Possible values: `F` — Female; `M` — Male; `O` — Other; `N` — Prefer not to say.", "type": "string", "enum": [ "F", "M", "O", "N" ], "example": "M" }, "updated_at": { "description": "The date and time the user was updated at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "created_at": { "description": "The date and time the user was created at", "type": "string", "format": "date-time", "example": "2016-03-07T07:49:41+00:00" }, "user_status": { "description": "The User's account status. Possible values: `PENDING` — account created but email not yet verified; `VERIFIED` — active, verified member; `GUEST` — signed up for an event without a full account; `ANON_GUEST` — anonymous guest participant.", "type": "string", "enum": [ "PENDING", "VERIFIED", "GUEST", "ANON_GUEST" ], "example": "VERIFIED" }, "membership_status": { "description": "The User's membership status for the current org. Present only when the user has a membership record for the org. Possible values: `ACCEPTED` — active member; `PENDING` — invitation sent, not yet accepted; `REMOVED` — membership removed by an organizer; `REJECTED` — invitation declined by the user; `INACTIVE` — membership deactivated; `LOBBY` — user is in the join queue awaiting approval.", "type": "string", "enum": [ "ACCEPTED", "PENDING", "REMOVED", "REJECTED", "INACTIVE", "LOBBY" ], "example": "ACCEPTED" }, "membership_role": { "description": "The User's membership role for the current org. Present only when the user has a membership record for the org. These are the standard membership roles surfaced to partners. Possible values: `ADMIN` — organization administrator with full management access; `ORGANIZER` — can create and manage projects and events; `VOLUNTEER` — standard volunteer member.", "type": "string", "enum": [ "ADMIN", "ORGANIZER", "VOLUNTEER" ], "example": "VOLUNTEER" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Campaigns", "description": "Campaigns" }, { "name": "Certifications", "description": "Certifications" }, { "name": "Forms", "description": "Forms" }, { "name": "Groups", "description": "Groups" }, { "name": "Organizations", "description": "Organizations" }, { "name": "Projects", "description": "Projects" }, { "name": "Users", "description": "Users" } ], "security": [ { "bearerAuth": [] } ] }