# Introduction
The Vome API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs and returns [JSON-encoded](http://www.json.org/) responses. It also uses standard HTTP response codes, authentication, and verbs.
If you wish to collaborate with us on the Vome API and provide feedback about our docs, you can visit our [support portal](https://support.vomevolunteer.com) to interact directly with our team.\
\
To use the Vome API, you must be using the Ultimate plan. If you need more information about the Ultimate plan and pricing, you can [explore our plans](https://www.vomevolunteer.com/plans). Once upgraded to Ultimate, you will have the capability of generating API keys to integrate different solutions with Vome. To learn more about how to create API keys, you can continue reading about [Authentication](/getting-started/publish-your-docs).
# Authentication
The Vome API uses an API key for authenticating requests, exclusively available to users who have subscribed to the Ultimate plan (learn more about our plans [here](https://www.vomevolunteer.com/plans)). Using an API key helps ensure that sensitive data remains secure and accessible only to authorized users.\
\
**Generating an API key**\
\
1\. **Login** to your administrative account on Vome\
2\. Using the left-hand navigation, click **Integrations & Apps**\
3\. Click the option **API & webhooks** to bring you to the developer dashboard\
4\. Click **Generate secret key**\
5\. Add a **title** to easily identify the use of this API key and click **Generate key**\
6\. Copy the secret key and keep it somewhere safe! You will not be able to view this secret key once you close the popup. You will need this secret key to integrate Vome's endpoints with 3rd party software, as it is what is used to authenticate the requests.
#### Using the API key
With the API key, you can authenticate your requests by including it in the headers (as shown below):
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/data", headers=headers)
```
#### Security practices
* **Keep Your Key Secure**: Your API key enables access to Vome data, so never share your API keys in publicly accessible areas such as GitHub, client-side code, etc.
* **Use HTTPS**: All API requests must be made over HTTPS. Calls made over plain HTTP will fail, and API requests without proper authentication will also be rejected.
***
# Errors
**Error Handling in Vome API**
The Vome API uses conventional HTTP status codes to indicate the success or failure of API requests. This page outlines common HTTP status codes you might encounter and the corresponding error types with descriptions to help you handle these errors programmatically.
#### HTTP Status Code Summary
| Status Code | Description | Notes |
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------- |
| 200 | OK | The request was successful. |
| 400 | Bad Request | Invalid request format or parameters. |
| 401 | Unauthorized | Authentication credentials were not provided or are invalid. |
| 403 | Forbidden | The API key doesn’t have permissions to perform the request. |
| 404 | Not Found | The requested resource doesn’t exist. |
| 409 | Conflict | The request conflicts with another request. |
| 429 | Too Many Requests | Rate limiting has been applied. |
| 500, 502, 503, 504 | Server Errors | Issues on Vome's servers (rare). Please [contact us](https://support.vomevolunteer.com) if experienced. |
#### Error Types
Errors returned from the Vome API include a structured payload that helps identify the issue clearly. Below are the types of errors that could be returned:
* **api\_error**: Covers general API processing errors.
* **authentication\_error**: Problems related to authentication or authorization.
* **invalid\_request\_error**: Errors due to invalid request parameters.
* **rate\_limit\_error**: Errors related to exceeding the rate limit.
#### Error Object Attributes
* **type** (`enum`): The category of the error encountered (e.g., `api_error`, `authentication_error`).
* **code** (`string`): A more specific code indicating the type of error (optional).
* **message** (`string`): A human-readable explanation specific to this occurrence of the problem.
* **param** (`string`): The specific parameter related to the error (if applicable).
#### Example Error Response
Here’s how an error might be structured in a JSON response:
```json
{
"error": {
"type": "invalid_request_error",
"code": "missing_field",
"message": "The 'email' field is required.",
"param": "email"
}
}
```
#### Handling Errors
When handling errors from the Vome API, it is crucial to check the HTTP status code and the error type returned in the response. This information should guide the corrective measures:
1. **Validate Request Parameters**: Ensure that all required fields are included and that data formats are correct.
2. **Handle Rate Limits Gracefully**: Implement exponential backoff or request retry mechanisms with delays.
3. **Log and Monitor**: Keep detailed logs of the errors encountered and monitor the frequency to identify potential improvements in client-side integration or user data entry practices.
# Pagination
Pagination in Vome API
The Vome API supports navigating through large datasets by implementing cursor-based pagination. This feature allows clients to efficiently browse through lists of resources such as profiles or shift reservations, ensuring that applications can handle large amounts of data smoothly.
**How Pagination Works**
Pagination in the Vome API relies on two parameters to navigate through data: `page` and `limit`. These parameters help control the part of the dataset that the API returns on each request.
**Parameters**
* **page** (`integer`): Specifies the page number of the results to retrieve.
* **limit** (`integer`, optional, default is 10): Determines the number of records to return in one page. This number can range between 1 and 100, allowing flexibility depending on the needs of the client application.
**Example**
Fetch the first page of profiles with 25 records:
```http
GET /api/profiles/?page=1&limit=25
```
#### Response Structure
Paginated responses include navigation metadata:
```json
{
"count": 150,
"next": "https://api.vomevolunteer.com/api/profiles/search/?first_name=Aaron&is_offline=False&page=3&limit=15",
"previous": "https://api.vomevolunteer.com/api/profiles/search/?first_name=Aaron&is_offline=False&page=1&limit=15",
"results": [
{
"id": "ab687438-bf10-4569-b023-818a8e512936",
"logged_hours": 0,
"is_offline": true,
"is_following": false,
"emergency_contact": {
"name": "Jon Smiths",
"phone_number": "5555555555",
"relationship": "Father"
},
"medical_information": {
"description": "Allergies to peanuts",
"has_medical_info": true
},
"profile_details": {
"first_name": "Name",
"last_name": "Unit Price",
"full_name": "",
"email": "sampleuser+677@malinator.com",
"profile_image": "",
"phone_number": "",
"date_of_birth": null,
"gender": 2,
"gender_text": "",
"occupation": null,
"occupation_institution_name": "",
"skills": [],
"languages": [],
"address": "",
"created_at": "2026-04-01T11:06:26.396971Z",
"age": null,
"address_coordinates": []
},
"opportunities": [],
"most_recent_shift": null,
"completed_shifts": 0,
"profile_tags": [],
"custom_fields": [
{
"id": "851ca2f9-41b5-42c8-be84-d715ae6a2339",
"custom_field": {
"id": "009eb956-f8ba-45da-8654-d2d0ace71336",
"name": "Where are you from?",
"field_type": 0,
"is_active": true
},
"custom_field_value": {
"id": "10109097-f78e-4f09-86a3-4ac2a9517c9d",
"value": "CA",
"value_info": "CA"
}
}
]
},
]
}
```
#### Navigating Between Pages
* `next`: URL for the next page, if available.
* `previous`: URL for the previous page, if available.
####
# Profiles
This object represents a profile in an organization's database. A profile in an organization's database can be a Vome User or managed as an Offline profile. There are approximately 20 default fields that are stored automatically across all profiles on Vome. In addition, the organization can create custom fields or profile tags on their database to store any type of data across profiles.
**Endpoints**
* **GET** `/api/profiles/`
* **GET** `/api/profiles/{profile_id}/`
* **GET** `/api/profiles/search/`
\
This endpoint is used to manage and retrieve profile information from your Vome database. It allows you to retrieve a list of profiles or specific profiles.
***
# The Profile object
#### Example Response
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/profiles/?page=20", headers=headers)
```
```json
{
"count": 791,
"next": null,
"previous": "http://api.vomevolunteer.com/api/profiles/?page=79",
"results": [
{
"id": "a9a1028f-93a6-401d-9867-1fe59aa2d830",
"logged_hours": 55,
"is_offline": true,
"is_following": false,
"emergency_contact": {
"name": "Dana Lauren",
"phone_number": "+15145555555",
"relationship": "Sibling"
},
"medical_information": {
"description": "I have allergies to peanuts",
"has_medical_info": true
},
"profile_details": {
"first_name": "Sara",
"last_name": "Fried",
"full_name": "Sara Fried",
"email": "sara.fried@domain.com",
"profile_image": "/media/images/user/profile_image/94859378-6a55-44c9-97ce-a737ba5030ed.jpg",
"phone_number": "+15145555555",
"date_of_birth": "2004-05-03",
"gender": 0, //Female
"gender_text": "",
"occupation": 2, //Professional
"occupation_institution_name": "ABC Corporation",
"skills": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"skill_title": "Video Editing"
} ,
]
"languages": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"language_name": "French"
},
],
"address": "1111 Marcus Avenue, New Hyde Park, NY, USA",
"latitude_longitude": [
"40.7567681",
"-73.69960300000001"
],
"age": 26
},
"opportunities": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"opportunity": {
"id": "e478b142-ba67-4c83-a5f2-e87a95d513ee",
"title": "Opportunity A",
"category": {
"title": "Education Testing New"
}
}
},
],
"most_recent_shift": null,
"completed_shifts": 0,
"profile_tags": [
{
"id": "546cbf95-f9e8-4064-91e4-70eb0ed02e3d",
"tag": {
"id": "ec007482-7c9a-4ec0-963d-8cb0048ff2fc",
"tag_title": "Tag A"
}
},
{
"id": "b575b45d-895d-4983-a8e8-57df91ce1692",
"tag": {
"id": "990c1afb-b1e7-4acd-8103-a6697b116c35",
"tag_title": "Tag B"
}
}
],
"custom_fields": [
{
"id": "4ecc41e2-bb20-458c-986c-472da2208f0b",
"custom_field": {
"id": "b9e2d0f6-11df-434e-a5db-66bf770b3373",
"name": "Custom Title - Boolean Field A",
"field_type": 10, //Boolean field
"is_active": true
},
"created_at": "2024-09-19T17:35:35.210435Z",
"custom_field_value": {
"id": "50ffc051-4db3-444c-a477-1bfd5052b157",
"value": true
}
},
{
"id": "4c7aee40-ae20-4021-a18f-ca8e6e915f0a",
"custom_field": {
"id": "b46da1d3-40bd-4e67-b560-abe937ae3064",
"name": "Multi-Select (Colors)",
"field_type": 3, //Multiple selection field
"is_active": true,
"options": [
{
"id": "41788791-32a0-455b-83a4-1c33262b324a",
"value": "Blue",
"order": 1
},
{
"id": "aa6f4182-3236-4225-8597-46eed1775d10",
"value": "Green",
"order": 2
},
{
"id": "ed50ba9a-05cf-418b-b990-d19e5d7907ed",
"value": "Yellow",
"order": 3
}
]
},
"custom_field_value": [
{
"id": "73dea3c5-0f53-4c70-8925-106cb8493a21",
"value": {
"id": "41788791-32a0-455b-83a4-1c33262b324a",
"value": "Blue",
"order": 1
}
},
{
"id": "535ae6f4-99e4-4e56-b991-0017273a15ba",
"value": {
"id": "aa6f4182-3236-4225-8597-46eed1775d10",
"value": "Green",
"order": 2
}
}
]
},
]
}
]
}
```
### **Profile Object**
This object represents the primary data structure for profiles within the Vome API.
* **Attributes**:
* **count** (`integer`): The total number of profiles available.
* **next** (`string` | `null`): The URL to the next page of profiles.
* **previous** (`string` | `null`): The URL to the previous page of profiles.
* **results** (`array` of **Profile Detail Objects**): A list of profiles containing detailed information about each user in your database.
**Detailed information about individual profiles:**
* **id** (`string`): A unique identifier for the profile stored automatically by Vome.
* **logged\_hours** (`integer`): The total number of hours logged by the user at your organization across all of their reservations.
* **is\_offline** (`boolean`): Indicates whether the person is actively using Vome or is currently an offline profile managed only by the organization.
* **is\_following** (`boolean`): Indicates if the current user is following your organization to receive notifications about new available opportunities.
* [**emergency\_contact**](#user-content-fn-1)[^1]**:** Emergency contact details for the user, including the name relationship and phone number.
* [**medical\_information**](#medical-information-object) : Any basic medical information stored on behalf of this the user.
* [**profile\_details**](#profile-details-object) (**Profile Details Object**): Contains comprehensive details about the user (more information shown below) which are stored in the organization's Vome database.
* [**opportunities**](#opportunities-array) (**Opportunities Array**): Opportunities assigned for the user.
* **most\_recent\_shift** (`string` | `null`): The most recent shift the user was scheduled for.
* **completed\_shifts** (`integer`): The total number of shifts completed by the user. This count only includes the number of past reservations which had hours logged for them.
* [**profile\_tags** ](#tags-array)(**Tags Array**): Indicates the custom profile tags that have been associated with this user.
* [**custom\_fields** ](#custom-fields-array)(**Custom Fields Array**): A list of custom database fields and the values of those custom database fields for the given user..
#### **Emergency Contact Object**
Emergency contact details of the user.
* **name** (`string`): The full name of the emergency contact.
* **phone\_number** (`string`): The phone number of the emergency contact.
* **relationship** (`string`): The relationship of the contact to the user.
#### **Medical Information Object**
Details regarding the user's basic medical information provided.
* **description** (`string`): Description of basic medical information provided about the user.
* **has\_medical\_info** (`boolean`): Indicates whether there is any medical information inputted for this user.
#### **Profile Details Object**
Comprehensive details about the user's profile information.
* **first\_name**, **last\_name**, **full\_name** (`string`): The name of the user.
* **email** (`string`): Email address of the user.
* **profile\_image** (`string`): URL to the user's profile picture.
* **phone\_number** (`string`): Phone number of the user.
* **date\_of\_birth** (`string` | `null`): The date of birth of the user.
* **gender** (`string` | `null`): The gender of the user. \
\
`0` = Male\
`1` = Female\
`2` = Other (ability to input string in **gender\_text** field)\
`3` = User inputted they would rather not say
* **gender\_text** (`string`): Text description of the gender if the user inputted "Other" as the gender field.
* **occupation** (`string` | `null`): The occupation of the user.\
\
`0` = Student\
`1` = Professional\
`2` = Retiree (ability to input string in gender\_text field)\
`3` = Other
* **occupation\_institution\_name** (`string`): The institution affiliated with this user (only applicable when the user indicated their occupation is "Student" or "Professional").
* **skills**, **languages** (`array`): Lists detailing skills and languages attributed to the user.
* **address** (`string`): The complete address of the user.
* **address\_coordinates** (`array`): Geographic coordinates of the user if an address was address via Google Maps. If the address was added via the import process, this data would not be available.
* **age** (`integer` | `null`): The age of the use, calculated using the data of birth field.
#### **Opportunities Array**
List of opportunities assigned to the user's profile.
* **id** (`string`): Identifier for the relationship between the user and the opportunity.
* **opportunity** (**Opportunity Object**): includes which opportunities the user is assigned to.
* **id** (`string`): Identifier of the opportunity.
* **title** (`string`): Title of the opportunity.
* **category** (**category Object**): Includes the categories related to the opportunities the user is assigned to
* **id** (`string`): Identifier of the category.
* **title** (`string`): Title of the category.
#### **Tags Array**
Tags associated with the user's profile.
* **id** (`string`): Identifier for the relationship between the user and the profile tag.
* **tag** (**Tag Object**): The profile tag details.
* **id** (`string`): Identifier for the profile tag.
* **title** (`string`): Title of the profile tag.
#### **Custom Fields Array**
A custom field is a custom database field created by an admin in the Vome database. It allows the admin to create data fields, and store values for each of their users.
* **id** (`string`): Identifier for the relationship between a user’s custom\_field and custom\_field value
* **custom\_field** (**custom\_field Object**): The details of the custom field created by the organization.
* **id** (`string`): Identifier of the custom field.
* **name** (`string`): The title of the custom field.
* [**field\_type** ](#custom-field-types)(`string`): The type of custom field it is (i.e. general, date, boolean, etc.)
* **is\_active** (`boolean`): Whether the field is actively displayed on the Vome database default view.
* **options** (`array`): Only applicable if the admin created a single selection or multiple selection field, which would include the options that can be attributed to the user.
* **id** (`string`): Identifier of the option.
* **value** (`string`): Title/value of the option
* **order** (`string`): Order shown in the list
* **custom\_field\_value (custom\_field\_value Object):** The value of the custom field for the specific user. *There could be multiple objects for Multiple Selection type fields since the user can have multiple options attributed to them.*
* **id** (`string`): Identifier of the user's relationship to the custom field value.
* **value** (`value Object`): Identifier for a user's custom field value.
* **id** (`string`): Identifier for the user’s custom field.
* **value** (`string`): The value added
* **order** (`string`): The order shown (only applicable if it is a multiple selection field)
#### Custom Field Types
* **GENERAL** (`0`): General type field.
* **NUMBER** (`1`): Field for numeric values.
* **SINGLE SELECTION** (`2`): Field allowing a single option selection.
* **MULTIPLE SELECTION** (`3`): Field allowing multiple options selection.
* **DATE & TIME** (`4`): Field for date and time values.
* **EMAIL** (`5`): Field for email addresses.
* **ATTACHMENT** (`6`): Field for file attachments.
* **URL** (`7`): Field for URLs.
* **ADDRESS** (`8`): Field for addresses.
* **UNIQUE\_ID** (`9`): Field with a unique identifier.
* **BOOLEAN** (`10`): Field for true/false values.
* **FORMULA** (`11`): Field for calculated values.
* **DATE** (`12`): Field for date values.
[^1]:
# List all profiles
This endpoint is used to retrieve all profiles from your Vome database. It allows you to retrieve a list of profiles or specific profiles.
***
Endpoints
* **Retrieve Profiles List**: `GET /api/profiles/`
* **Retrieve Specific Page of Profiles**: `GET /api/profiles/?page={number}`
***
#### Example Request
```plaintext
GET /api/profiles/?page=20
```
#### Example Response
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/profiles/?page=20", headers=headers)
```
```json
{
"count": 791,
"next": null,
"previous": "http://api.vomevolunteer.com/api/profiles/?page=79",
"results": [
{
"id": "a9a1028f-93a6-401d-9867-1fe59aa2d830",
"logged_hours": 55,
"is_offline": true,
"is_following": false,
"emergency_contact": {
"name": "Dana Lauren",
"phone_number": "+15145555555",
"relationship": "Sibling"
},
"medical_information": {
"description": "I have allergies to peanuts",
"has_medical_info": true
},
"profile_details": {
"first_name": "Sara",
"last_name": "Fried",
"full_name": "Sara Fried",
"email": "sara.fried@domain.com",
"profile_image": "/media/images/user/profile_image/94859378-6a55-44c9-97ce-a737ba5030ed.jpg",
"phone_number": "+15145555555",
"date_of_birth": "2004-05-03",
"gender": 0, //Female
"gender_text": "",
"occupation": 2, //Professional
"occupation_institution_name": "ABC Corporation",
"skills": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"skill_title": "Video Editing"
} ,
]
"languages": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"language_name": "French"
},
],
"address": "1111 Marcus Avenue, New Hyde Park, NY, USA",
"latitude_longitude": [
"40.7567681",
"-73.69960300000001"
],
"age": 26
},
"opportunities": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"opportunity": {
"id": "e478b142-ba67-4c83-a5f2-e87a95d513ee",
"title": "Opportunity A",
"category": {
"title": "Education Testing New"
}
}
},
],
"most_recent_shift": null,
"completed_shifts": 0,
"profile_tags": [
{
"id": "546cbf95-f9e8-4064-91e4-70eb0ed02e3d",
"tag": {
"id": "ec007482-7c9a-4ec0-963d-8cb0048ff2fc",
"tag_title": "Tag A"
}
},
{
"id": "b575b45d-895d-4983-a8e8-57df91ce1692",
"tag": {
"id": "990c1afb-b1e7-4acd-8103-a6697b116c35",
"tag_title": "Tag B"
}
}
],
"custom_fields": [
{
"id": "4ecc41e2-bb20-458c-986c-472da2208f0b",
"custom_field": {
"id": "b9e2d0f6-11df-434e-a5db-66bf770b3373",
"name": "Custom Title - Boolean Field A",
"field_type": 10, //Boolean field
"is_active": true
},
"created_at": "2024-09-19T17:35:35.210435Z",
"custom_field_value": {
"id": "50ffc051-4db3-444c-a477-1bfd5052b157",
"value": true
}
},
{
"id": "4c7aee40-ae20-4021-a18f-ca8e6e915f0a",
"custom_field": {
"id": "b46da1d3-40bd-4e67-b560-abe937ae3064",
"name": "Multi-Select (Colors)",
"field_type": 3, //Multiple selection field
"is_active": true,
"options": [
{
"id": "41788791-32a0-455b-83a4-1c33262b324a",
"value": "Blue",
"order": 1
},
{
"id": "aa6f4182-3236-4225-8597-46eed1775d10",
"value": "Green",
"order": 2
},
{
"id": "ed50ba9a-05cf-418b-b990-d19e5d7907ed",
"value": "Yellow",
"order": 3
}
]
},
"custom_field_value": [
{
"id": "73dea3c5-0f53-4c70-8925-106cb8493a21",
"value": {
"id": "41788791-32a0-455b-83a4-1c33262b324a",
"value": "Blue",
"order": 1
}
},
{
"id": "535ae6f4-99e4-4e56-b991-0017273a15ba",
"value": {
"id": "aa6f4182-3236-4225-8597-46eed1775d10",
"value": "Green",
"order": 2
}
}
]
},
]
}
]
}
```
# Retrieve a profile
This endpoint retrieves detailed information about a specific database profile by ID.
Endpoint
```
GET /api/profiles/{profile_id}/
```
Replace `{profile_id}` with the actual ID of the profile you wish to retrieve.
#### Example Request
```plaintext
GET /api/profiles/a9a1028f-93a6-401d-9867-1fe59aa2d830/
```
#### Authorization
Requests to this endpoint must include an `API-KEY` in the header for authentication:
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/profiles/a9a1028f-93a6-401d-9867-1fe59aa2d830/", headers=headers)
```
#### Response Object
The response object includes comprehensive details about the volunteer's profile:
```json
{
"id": "a9a1028f-93a6-401d-9867-1fe59aa2d830",
"logged_hours": 0,
"is_offline": true,
"is_following": false,
"emergency_contact": {
"name": "Dana Lauren",
"phone_number": "+15145555555",
"relationship": "Sibling"
},
"medical_information": {
"description": "I have allergies to peanuts",
"has_medical_info": true
},
"profile_details": {
"first_name": "Sara",
"last_name": "Fried",
"full_name": "Sara Fried",
"email": "sara.fried@domain.com",
"profile_image": "/media/images/user/profile_image/94859378-6a55-44c9-97ce-a737ba5030ed.jpg",
"phone_number": "+15145555555",
"date_of_birth": "2004-05-03",
"gender": 1, //Female
"gender_text": "",
"occupation": 2, //Professional
"occupation_institution_name": "ABC Corporation",
"skills": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"skill_title": "Video Editing"
},
]
"languages": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"language_name": "French"
},
],
"address": "1111 Marcus Avenue, New Hyde Park, NY, USA",
"latitude_longitude": [
"40.7567681",
"-73.69960300000001"
],
"age": 26
},
"opportunities": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"opportunity": {
"id": "e478b142-ba67-4c83-a5f2-e87a95d513ee",
"title": "Opportunity A",
"category": {
"title": "Education Testing New"
}
}
},
],
"most_recent_shift": null,
"completed_shifts": 0,
"profile_tags": [
{
"id": "546cbf95-f9e8-4064-91e4-70eb0ed02e3d",
"tag": {
"id": "ec007482-7c9a-4ec0-963d-8cb0048ff2fc",
"tag_title": "Tag A"
}
},
{
"id": "b575b45d-895d-4983-a8e8-57df91ce1692",
"tag": {
"id": "990c1afb-b1e7-4acd-8103-a6697b116c35",
"tag_title": "Tag B"
}
}
],
"custom_fields": [
{
"id": "4ecc41e2-bb20-458c-986c-472da2208f0b",
"custom_field": {
"id": "b9e2d0f6-11df-434e-a5db-66bf770b3373",
"name": "Custom Title - Boolean Field A",
"field_type": 10, //Boolean field
"is_active": true
},
"created_at": "2024-09-19T17:35:35.210435Z",
"custom_field_value": {
"id": "50ffc051-4db3-444c-a477-1bfd5052b157",
"value": true
}
},
{
"id": "4c7aee40-ae20-4021-a18f-ca8e6e915f0a",
"custom_field": {
"id": "b46da1d3-40bd-4e67-b560-abe937ae3064",
"name": "Multi-Select (Colors)",
"field_type": 3, //Multiple selection field
"is_active": true,
"options": [
{
"id": "41788791-32a0-455b-83a4-1c33262b324a",
"value": "Blue",
"order": 1
},
{
"id": "aa6f4182-3236-4225-8597-46eed1775d10",
"value": "Green",
"order": 2
},
{
"id": "ed50ba9a-05cf-418b-b990-d19e5d7907ed",
"value": "Yellow",
"order": 3
}
]
},
"created_at": "2024-09-19T17:35:44.867923Z",
"custom_field_value": [
{
"id": "73dea3c5-0f53-4c70-8925-106cb8493a21",
"value": {
"id": "41788791-32a0-455b-83a4-1c33262b324a",
"value": "Blue",
"order": 1
}
},
{
"id": "535ae6f4-99e4-4e56-b991-0017273a15ba",
"value": {
"id": "aa6f4182-3236-4225-8597-46eed1775d10",
"value": "Green",
"order": 2
}
}
]
},
]
}
```
For a complete description of each field in this response object, you can visit: [Profiles](/resources/editor)
# Write Operations
Vome API offers endpoints to create, update or upsert (create and/or update) profiles directly in your Vome database.
***
**How we does Vome identify a profile in your database?**\
\
We offer 3 flexible ways for your team to identify profiles from your Vome database.
1. **Email address (default method)**: The email address field is a **username** in the Vome system, and therefore can be used to match profiles from other systems.
*For example, let's say you want to update existing profiles in your Vome database. One of the profiles getting updated will be Bill Smith (who has an email of ). When sending a PUT request to update profiles, we will check to see if there is a profile with the email to update).*
2. **Vome ID:** Every profile on Vome has a unique identifier string value associated with their account. You can access these Vome ID values when retrieving profiles\
\
*For example, let's say you want to update existing profiles in your Vome database. One of the profiles getting updated will be Bill Smith (who has a Vome ID equal to "123"). When sending a PUT request to update profiles, we will check to see if there is a profile with the Vome ID of "123" to update).*
3. **Custom ID field**: On Vome, we offer the ability for admins to create **custom fields** in their database. We offer a **field type** called "**Unique ID**" which allows you to add Unique ID values and associate them with profiles. \
\
*For example, you can create a Vome database field. The field type would be "Unique ID" and the name of the field entered is "Salesforce ID". By doing so, we can then match profiles based on this user value for this custom field.*
#### Endpoints
```plaintext
POST api/profiles/bulk-create/
PUT api/profiles/bulk-update/
PUT api/profiles/bulk-upsert/
```
#### API specification
* **unique\_identifier** (`object`): Includes the setting of how you would like to identify users from your database.
* **identifier\_type** (`integer` | `null`):
* `0` = Email
* `1` = Vome ID
* `2` = Custom Field - Unique ID
* **unique\_id** (`string` | `null`): If the **identifier\_type** is set to **Custom Field - Unique ID**, this would be the ID of the field from Vome.
* *For example, if you created a new field on the Vome database calle**d Salesforce User ID**, when retrieving a profile using our endpoint, you will see this field has an **associated field ID**, which can be used here.*
* **invite\_user\_to\_vome** (`boolean`| `null`): Whether you choose to invite the new user to claim their profile on Vome. If you choose to make this **False**, the profile will remain **Offline** in your database unless invited in the future.
* **invite\_language** (`string` | `null`): You can pass "EN" or "FR".
* If you choose to invite the user to claim their profile, indicate whether you want to send the invitation in English or French
* **invite\_message** (`string` | `null`): You can send HTML inside of a string.
* If you choose to invite the user to claim their profile, you can include a custom message to be included in the email notification sent to them.
* **user\_data** (`array` | `null`): An array storing profile and other related information to the user. For complete information about the fiels that relate to the user profile, please review [the Profile object](/resources/editor/the-profile-object).
#### Example Request Payload
```json
{
"unique_identifier": {
"identifier_type":0, //Email address
"unique_custom_field": ""
},
"invite_user_to_vome": true,
"invite_language": 'EN',
"invite_message": '
We cannot wait for you to claim your profile!
',
"volunteers_data": [
{
"emergency_contact": {
"name": "Jon Smith",
"phone_number": "5555555555",
"relationship": "Father"
},
"medical_information": {
"description": "Allergies to peanuts",
"has_medical_info": "true"
},
"occupation_info":{
"occupation":0, //Student
"occupation_institution_name":"University of Memphis"
},
"profile_data": {
"id":"d2fcbe43-1eba-419e-a489-3d471f7658ff",
"first_name": "Lily",
"last_name": "Smith",
"email":"lily.smith123@domain.com",
"phone_number": "555555555",
"date_of_birth": "1998-06-06",
"gender": 1, //Female
"address": "7 Freedom Trail, Medway, Norfolk, MA, USA",
"address_coordinates": [
"42.14579519999999",
"-71.4391298"
]
},
"custom_field_data": [
{
"custom_field_id": "395fd06d-48ca-41a0-be0c-3cd22fdad976",
"custom_field_name": "Salesforce ID",
"custom_field_user_value": "fe8fwe7f7897487r87hb"
},
{
"custom_field_id": "78c03e94-097b-4f00-8aaa-6b7e4ddf1e93",
"custom_field_name": "T-shirt size",
"custom_field_user_value": "Medium"
}
]
}
]
}
```
# Create profiles
This endpoint is used to create profiles in your Vome database. Profiles will only be created if they do not already exist.
Please note, you must add a **first name**, **last name** and **email address** when creating profiles. The email address must be unique across profiles in your database.
#### Endpoint
```plaintext
POST api/profiles/bulk-create/
```
#### Example Request Payload
```json
{
"unique_identifier": {
"identifier_type":0, //Email address
"unique_custom_field": ""
},
"invite_user_to_vome": true,
"invite_language": 'EN',
"invite_message": '
We cannot wait for you to claim your profile!
',
"users_data": [
{
"emergency_contact": {
"name": "Jon Smith",
"phone_number": "5555555555",
"relationship": "Father"
},
"medical_information": {
"description": "Allergies to peanuts",
"has_medical_info": "true"
},
"occupation_info":{
"occupation":0, //Student
"occupation_institution_name":"University of Memphis"
},
"profile_data": {
"id":"d2fcbe43-1eba-419e-a489-3d471f7658ff",
"first_name": "Lily",
"last_name": "Smith",
"email":"lily.smith123@domain.com",
"phone_number": "555555555",
"date_of_birth": "1998-06-06",
"gender": 1, //Female
"address": "7 Freedom Trail, Medway, Norfolk, MA, USA",
"address_coordinates": [
"42.14579519999999",
"-71.4391298"
]
},
"custom_field_data": [
{
"custom_field_id": "395fd06d-48ca-41a0-be0c-3cd22fdad976",
"custom_field_name": "Salesforce ID",
"custom_field_user_value": "fe8fwe7f7897487r87hb"
},
{
"custom_field_id": "78c03e94-097b-4f00-8aaa-6b7e4ddf1e93",
"custom_field_name": "T-shirt size",
"custom_field_user_value": "Medium"
}
]
}
]
}
```
# Update profiles
This endpoint is used to update profiles in your Vome database. Profiles will only be updated if they are matched with your identifier of choice.
#### Endpoint
```plaintext
PUT api/profiles/bulk-update/
```
#### Example Request Payload
```json
{
"unique_identifier": {
"identifier_type":0, //Email address
"unique_custom_field": ""
},
"invite_user_to_vome": true,
"invite_language": 'EN',
"invite_message": '
We cannot wait for you to claim your profile!
',
"users_data": [
{
"emergency_contact": {
"name": "Jon Smith",
"phone_number": "5555555555",
"relationship": "Father"
},
"medical_information": {
"description": "Allergies to peanuts",
"has_medical_info": "true"
},
"occupation_info":{
"occupation":0, //Student
"occupation_institution_name":"University of Memphis"
},
"profile_data": {
"id":"d2fcbe43-1eba-419e-a489-3d471f7658ff",
"first_name": "Lily",
"last_name": "Smith",
"email":"lily.smith123@domain.com",
"phone_number": "555555555",
"date_of_birth": "1998-06-06",
"gender": 1, //Female
"address": "7 Freedom Trail, Medway, Norfolk, MA, USA",
"address_coordinates": [
"42.14579519999999",
"-71.4391298"
]
},
"custom_field_data": [
{
"custom_field_id": "395fd06d-48ca-41a0-be0c-3cd22fdad976",
"custom_field_name": "Salesforce ID",
"custom_field_user_value": "fe8fwe7f7897487r87hb"
},
{
"custom_field_id": "78c03e94-097b-4f00-8aaa-6b7e4ddf1e93",
"custom_field_name": "T-shirt size",
"custom_field_user_value": "Medium"
}
]
}
]
}
```
# Upsert profiles
This endpoint is used to create and/or update profiles in your Vome database. This means that if we find a match in your database, we will update the profile. If there is no match, we will attempt to create a new profile.
Please note, you must add a **first name**, **last name** and **email address** when trying to create profiles. The email address must be unique across profiles in your database.
#### Endpoint
```plaintext
POST api/profiles/bulk-upsert/
```
#### Example Request Payload
```json
{
"unique_identifier": {
"identifier_type":0, //Email address
"unique_custom_field": ""
},
"invite_user_to_vome": true,
"invite_language": 'EN',
"invite_message": '
We cannot wait for you to claim your profile!
',
"users_data": [
{
"emergency_contact": {
"name": "Jon Smith",
"phone_number": "5555555555",
"relationship": "Father"
},
"medical_information": {
"description": "Allergies to peanuts",
"has_medical_info": "true"
},
"occupation_info":{
"occupation":0, //Student
"occupation_institution_name":"University of Memphis"
},
"profile_data": {
"id":"d2fcbe43-1eba-419e-a489-3d471f7658ff",
"first_name": "Lily",
"last_name": "Smith",
"email":"lily.smith123@domain.com",
"phone_number": "555555555",
"date_of_birth": "1998-06-06",
"gender": 1, //Female
"address": "7 Freedom Trail, Medway, Norfolk, MA, USA",
"address_coordinates": [
"42.14579519999999",
"-71.4391298"
]
},
"custom_field_data": [
{
"custom_field_id": "395fd06d-48ca-41a0-be0c-3cd22fdad976",
"custom_field_name": "Salesforce ID",
"custom_field_user_value": "fe8fwe7f7897487r87hb"
},
{
"custom_field_id": "78c03e94-097b-4f00-8aaa-6b7e4ddf1e93",
"custom_field_name": "T-shirt size",
"custom_field_user_value": "Medium"
}
]
}
]
}
```
# Search profiles
This endpoint allows for searching profiles based on specific [query parameters](#query-parameters) like `first_name` and `is_offline`, etc. It supports filtering to refine search results and utilizes pagination to handle large datasets efficiently.
#### Endpoint
```
GET /api/profiles/search/
```
**Query Parameters:**
Core Filters
• **id (uuid)**: Filters reservations by the ID.
• **first\_name** (`string`): Filters profiles by the first name.
• **last\_name** (`string`): Filters profiles by the last name.
• **email** (`string`): Filters profiles by the email.
• **created\_at** (string, ISO-8601): Filters profiles by profile\_details.created\_at.
* created\_at.gte (string, ISO-8601): Filters by profile\_details.created\_at >= value.
* created\_at.gt (string, ISO-8601): Filters by profile\_details.created\_at > value (strictly after).
* created\_at.lte (string, ISO-8601): Filters by profile\_details.created\_at <= value.
* created\_at.lt (string, ISO-8601): Filters by profile\_details.created\_at < value (strictly before).
####
#### *Sample Requests*
# id
GET /api/profiles/search/?id=a31a7f99-87c2-4f13-af1e-502a724634d7
# first_name
GET /api/profiles/search/?first_name=Aaron
# last_name
GET /api/profiles/search/?last_name=James
# email
GET /api/profiles/search/?last_name=aaronjames03@domain.com
# created_at
GET /api/profiles/search/?created_at=2024-09-06T02:57:15.008656Z
# created_at.gt
GET /api/profiles/search/?created_at.gt=2024-09-06T02:57:15.008656Z
# created_at.gte
GET /api/profiles/search/?created_at.gte=2024-09-06T02:57:15.008656Z
# created_at.lt
GET /api/profiles/search/?created_at.lt=2024-09-06T02:57:15.008656Z
# created_at.lte
GET /api/profiles/search/?created_at.lte=2024-09-06T02:57:15.008656Z
**Filtering using Custom Fields**
* **custom\_fields.custom\_field\_value.value\_info.value (string)**: Filters profiles by the value\_info's value of the custom\_field\_value within the custom fields.
```
GET /api/profiles/search/?custom_fields.custom_field_value.value_info.value=blue
```
#### Authorization
Requests to this endpoint require an `API-KEY` in the header:
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/profiles/search/?first_name=Aaron&last_name=James", headers=headers)
```
Response Object
The response includes a count of total profiles found, navigation links for [pagination](/getting-started/pagination), and an array of profile data:
```json
{
"count": 4,
"next": null,
"previous": "http://api.vomevolunteer.com/api/profiles/?page=79",
"results": [
{
"id": "a9a1028f-93a6-401d-9867-1fe59aa2d830",
"logged_hours": 0,
"is_offline": true,
"is_following": false,
"emergency_contact": {
"name": "Dana Lauren",
"phone_number": "+15145555555",
"relationship": "Sibling"
},
"medical_information": {
"description": "I have allergies to peanuts",
"has_medical_info": true
},
"profile_details": {
"first_name": "Sara",
"last_name": "Fried",
"full_name": "Sara Fried",
"email": "sara.fried@domain.com",
"profile_image": "/media/images/user/profile_image/94859378-6a55-44c9-97ce-a737ba5030ed.jpg",
"phone_number": "+15145555555",
"date_of_birth": "2004-05-03",
"gender": 0, //Female
"gender_text": "",
"occupation": 2, //Professional
"occupation_institution_name": "ABC Corporation",
"skills": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"skill_title": "Video Editing"
},
]
"languages": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"language_name": "French"
},
],
"address": "1111 Marcus Avenue, New Hyde Park, NY, USA",
"latitude_longitude": [
"40.7567681",
"-73.69960300000001"
],
"age": 26
},
"opportunities": [
{
"id": "64fd9793-0b67-4b02-a163-f2a7216292af",
"opportunity": {
"id": "e478b142-ba67-4c83-a5f2-e87a95d513ee",
"title": "Opportunity A",
"category": {
"title": "Education Testing New"
}
}
},
],
"most_recent_shift": null,
"completed_shifts": 0,
"profile_tags": [
{
"id": "546cbf95-f9e8-4064-91e4-70eb0ed02e3d",
"tag": {
"id": "ec007482-7c9a-4ec0-963d-8cb0048ff2fc",
"tag_title": "Tag A"
}
},
{
"id": "b575b45d-895d-4983-a8e8-57df91ce1692",
"tag": {
"id": "990c1afb-b1e7-4acd-8103-a6697b116c35",
"tag_title": "Tag B"
}
}
],
"custom_fields": [
{
"id": "4ecc41e2-bb20-458c-986c-472da2208f0b",
"custom_field": {
"id": "b9e2d0f6-11df-434e-a5db-66bf770b3373",
"name": "Custom Title - Boolean Field A",
"field_type": 10, //Boolean field
"is_active": true
},
"created_at": "2024-09-19T17:35:35.210435Z",
"custom_field_value": {
"id": "50ffc051-4db3-444c-a477-1bfd5052b157",
"value": true
}
},
{
"id": "4c7aee40-ae20-4021-a18f-ca8e6e915f0a",
"custom_field": {
"id": "b46da1d3-40bd-4e67-b560-abe937ae3064",
"name": "Multi-Select (Colors)",
"field_type": 3, //Multiple selection field
"is_active": true,
"options": [
{
"id": "41788791-32a0-455b-83a4-1c33262b324a",
"value": "Blue",
"order": 1
},
{
"id": "aa6f4182-3236-4225-8597-46eed1775d10",
"value": "Green",
"order": 2
},
{
"id": "ed50ba9a-05cf-418b-b990-d19e5d7907ed",
"value": "Yellow",
"order": 3
}
]
},
"created_at": "2024-09-19T17:35:44.867923Z",
"custom_field_value": [
{
"id": "73dea3c5-0f53-4c70-8925-106cb8493a21",
"value": {
"id": "41788791-32a0-455b-83a4-1c33262b324a",
"value": "Blue",
"order": 1
}
},
{
"id": "535ae6f4-99e4-4e56-b991-0017273a15ba",
"value": {
"id": "aa6f4182-3236-4225-8597-46eed1775d10",
"value": "Green",
"order": 2
}
}
]
},
]
}
]
}
```
For a complete description of each field in this response object, you can visit: [Profiles](/resources/editor)
# List profile fields
Retrieve the full list of profile fields available in your database (default + custom).
Endpoint
```
GET /api/profile-fields/
```
#### Authorization
Requests to this endpoint must include an `API-KEY` in the header for authentication:
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com//api/profile-fields/", headers=headers)
```
#### Response Object
The response object includes comprehensive details about the types of fields you can retrieve.
*Note: The list includes system fields (e.g., `email`, `phone_number`, `profile_tags`) and any custom fields your organization created (e.g., attachments, booleans, enums, dates). Custom field `id`s are UUIDs and stable.*\
\
*For a list of all field types available, please see* [The Profile object](/resources/editor/the-profile-object).
```json
[
{
"id": "id",
"label": "Id",
"type": "uuid",
"is_custom": false
},
{
"id": "first_name",
"label": "First name",
"type": "string",
"is_custom": false
},
{
"id": "last_name",
"label": "Last name",
"type": "string",
"is_custom": false
},
{
"id": "opportunities",
"label": "Opportunities",
"type": "json",
"is_custom": false
},
{
"id": "categories",
"label": "Categories",
"type": "json",
"is_custom": false
},
{
"id": "sequences",
"label": "Sequences",
"type": "json",
"is_custom": false
},
{
"id": "next_shift_date",
"label": "Next shift date",
"type": "datetime",
"is_custom": false
},
{
"id": "opportunity_tags",
"label": "Opportunity tags",
"type": "json",
"is_custom": false
},
{
"id": "impact_value",
"label": "Impact value",
"type": "decimal",
"is_custom": false
},
{
"id": "date_invited",
"label": "Date invited",
"type": "datetime",
"is_custom": false
},
{
"id": "last_login_date",
"label": "Last login date",
"type": "datetime",
"is_custom": false
},
{
"id": "completed_shifts",
"label": "Completed shifts",
"type": "integer",
"is_custom": false
},
{
"id": "logged_hours",
"label": "Logged hours",
"type": "duration",
"is_custom": false
},
{
"id": "gender",
"label": "Gender",
"type": "integer",
"is_custom": false
},
{
"id": "email",
"label": "Email",
"type": "string",
"is_custom": false
},
{
"id": "phone_number",
"label": "Phone number",
"type": "string",
"is_custom": false
},
{
"id": "address",
"label": "Address",
"type": "string",
"is_custom": false
},
{
"id": "date_of_birth",
"label": "Date of birth",
"type": "date",
"is_custom": false
},
{
"id": "birthday",
"label": "Birthday",
"type": "date",
"is_custom": false
},
{
"id": "emergency_contact_name",
"label": "Emergency contact name",
"type": "string",
"is_custom": false
},
{
"id": "emergency_contact_relationship",
"label": "Emergency contact relationship",
"type": "string",
"is_custom": false
},
{
"id": "emergency_contact_phone_number",
"label": "Emergency contact phone number",
"type": "string",
"is_custom": false
},
{
"id": "skills",
"label": "Skills",
"type": "json",
"is_custom": false
},
{
"id": "languages",
"label": "Languages",
"type": "json",
"is_custom": false
},
{
"id": "occupation",
"label": "Occupation",
"type": "integer",
"is_custom": false
},
{
"id": "organization",
"label": "Organization",
"type": "string",
"is_custom": false
},
{
"id": "last_shift_date",
"label": "Last shift date",
"type": "date",
"is_custom": false
},
{
"id": "start_date",
"label": "Start date",
"type": "date",
"is_custom": false
},
{
"id": "profile_image",
"label": "Profile image",
"type": "string",
"is_custom": false
},
{
"id": "gender_text",
"label": "Gender text",
"type": "string",
"is_custom": false
},
{
"id": "address_coordinates",
"label": "Address coordinates",
"type": "json",
"is_custom": false
},
{
"id": "profile_tags",
"label": "Profile tags",
"type": "json",
"is_custom": false
},
{
"id": "is_offline",
"label": "Is offline",
"type": "boolean",
"is_custom": false
},
{
"id": "is_following",
"label": "Is following",
"type": "boolean",
"is_custom": false
},
{
"id": "emergency_contact",
"label": "Emergency contact",
"type": "json",
"is_custom": false
},
{
"id": "medical_information",
"label": "Medical information",
"type": "json",
"is_custom": false
},
{
"id": "date_claimed_profile",
"label": "Date claimed profile",
"type": "datetime",
"is_custom": false
},
{
"id": "9a291c01-37c8-4296-9665-ac94bc006d34",
"label": "Annual health screening date",
"type": "date",
"field_type": 12,
"is_custom": true
},
{
"id": "59082000-478d-4fe2-858d-14641400b079",
"label": "Favourite color",
"type": "enum",
"field_type": 3,
"is_custom": true
},
{
"id": "b73d02d7-1682-4b72-95d4-da136263e63c",
"label": "Active status",
"type": "boolean",
"field_type": 10,
"is_custom": true
},
{
"id": "92a2ad55-0553-4e98-8caa-9f0aaf647a10",
"label": "Attachment field sample",
"type": "string",
"field_type": 6,
"is_custom": true
},
{
"id": "6ff1aa11-7f05-4fee-b63c-dfaae6414e84",
"label": "Cover letter attachment",
"type": "string",
"field_type": 6,
"is_custom": true
},
{
"id": "42be3f30-14e1-453f-800c-64f3801c4f8a",
"label": "Resume",
"type": "string",
"field_type": 6,
"is_custom": true
},
{
"id": "47450645-b3a4-45aa-a10b-92ebdda27265",
"label": "Salesforce id",
"type": "string",
"field_type": 9,
"is_custom": true
},
]
```
For a complete description of each field in this response object, you can visit: [Profiles](/resources/editor)
# Reservations
This object represents a user's reservation to a shift. A shift can have one or more reservations attached to them (i.e. Jon and Sarah are both scheduled to the same shift on Thursday at 1-3pm).\
\
*If you're not familiar with Vome's system, the hierarchy works as follows: Category > Opportunity > Shift* \
\
Within a shift, there can be custom details added such as a shift title, the number of spots permitted, and other shift-related details. \
\
Once a user is added to a shift, it creates a reservation object, which stores the details of of the user's status (i.e. if they're reserved or cancelled), their arrival and departure time, the number of hours they logged, and so forth.\
\
**Endpoints**
* **GET** `/api/reservations/`
* **GET** `/api/reservations/{reservation_id}/`
* **GET** `/api/reservations/search/`\
# The Reservation object
**Response Object**:
```json
{
"id": "3b87b2ee-5063-471d-a70a-051d165ca1d0",
"shift": {
"id": "1f7bb9e7-d891-42bc-b2a5-533cc02ad480",
"created_at": "2021-07-07T15:41:20.968717Z",
"shift_start_at": "2021-07-14T17:00:00Z",
"shift_end_at": "2021-07-14T19:00:00Z",
"spots": 1,
"shift_title": "Shift Title A",
"shift_description": null
},
"created_at": "2021-07-07T15:41:20.970080Z",
"status": 6, //Hours logged
"arrival_time": "2021-07-14T17:00:00Z",
"departure_time": "2021-07-14T19:00:00Z",
"hours_approved_by": {
"first_name": "Daniella",
"last_name": "Smith",
"email": "daniella_smith@domain.com"
},
"logged_hours": 2.0,
"user": {
"id": "443f05ad-b1be-43bc-a213-3483471bc7fa",
"first_name": "Lela",
"last_name": "Craig",
"email": "Lela_craig@mailinator.com",
"gender": 1, //Female
"address": "3949 Decarie Boulevard, Montreal, QC, Canada",
"phone_number": "929384838",
"date_of_birth": "1973-03-04",
"timezone": "America/Toronto",
"address_coordinates": [
"45.5011136",
"-73.5793778"
]
},
"opportunity": {
"id": "14e21aad-869d-4384-be7b-e12cb8c0dc3d",
"category": {
"id": "9d20cefb-002a-42d9-bce4-9937dd8444b5",
"title": "Program ABC",
"description": "Description of Program ABC"
},
"title": "Transportation",
"description": "Description of transportation"
}
}
```
The response object returns detailed information about a user's reservation. Here's a summary of the key fields:
* **id** (`string`): The unique identifier for the user's reservation to the shift.
* **shift** (`object`): Information about the related shift, including:
* **id** (`string`): Identifier for the shift.
* **created\_at** (`string`): The timestamp when the shift was created.
* **shift\_start\_at**, **shift\_end\_at** (`string`): The start and end times of the shift.
* **spots** (`integer`): Number of spots associated with the shift.
* **shift\_title**, **shift\_description** (`string`): Title and description of the shift.
* **created\_at** (`string`): The timestamp when the reservation was created.
* **status** (`integer`): Integer representing the reservation status, where:
* `0`: Shift request pending
* `1`: Reserved
* `2`: Shift request declined
* `3`: Attendance confirmed
* `4`: Absent
* `5`: Checked-in
* `6`: Hours logged
* `7`: Hour claim pending
* `8`: Cancelled
* **logged\_hours** (`array`): The total hours logged for the reservation.
* **hours\_approved\_by** (`array`): Information on the person who approved the hours, including name and email. This is only applicable if the admin checked-out the user from their profile. If the user was logged using the QR code, it would be `null`.
* **first\_name** (`string`): First name of the admin who approved the hours.
* **last\_name** (`string`): Last name of the admin who approved the hours.
* **email** (`string`): Email address of the admin who approved the hours.
* **arrival\_time** and **departure\_time** (`string`)**:** These represent the check-in and check-out times, respectively. They are used to calculate the hours logged for the reservation.
* **user** (**User Object**): Details about the user, including:
* **id**: Unique identifier of the user.
* **first\_name** (`string`): First name of the user.
* **last\_name** (`string`): Last name of the user.
* **email** (`string`): Email address of the user.
* **gender** (`integer`): Integer indicating gender, where:
* `0` = Male
* `1` = Female
* `2` = Other
* `3` = Rather not say
* **address** (`string`): The complete address of the user.
* **phone\_number** (`string`): Phone number of the user.
* **date\_of\_birth** (`string`): The date of birth of the user.
* **timezone** (`string` ): Timezone of the user
* **address\_coordinates** (`array`): Geographic coordinates of the user if an address was address via Google Maps. If the address was added via the import process, this data would not be available.
* **opportunity** (**Opportunity Object**): Details about the associated opportunity to this shift, including
* **id** (`string`): Identifier of the opportunity.
* **title** (`string`): Title of the opportunity.
* **description** (`string`): Description of the opportunity.
* **category** (**Category Object**): Details of the related category to this opportunity
* **id** (`string`): Identifier of the category.
* **title** (`string`): Title of the category.
* **description** (`string`): Description of the category.
# List all reservations
**Endpoint and Request Method**:
* **GET** `/api/reservations/`
* This endpoint is used to retrieve a list of all reservations.
**Example Request**:
* `GET https://api.vomevolunteer.com/api/reservations/`
**Authorization**:
* Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/reservations/", headers=headers)
```
**Response Structure**:
* The response is an array of objects, each representing a reservation along with associated details about the shift, user, and opportunity.
**Response Object**:
```json
{
"count": 832,
"next": "http://3.96.242.26:8030/api/reservations/?page=2",
"previous": null,
"results": [
{
"id": "3b87b2ee-5063-471d-a70a-051d165ca1d0",
"shift": {
"id": "1f7bb9e7-d891-42bc-b2a5-533cc02ad480",
"created_at": "2021-07-07T15:41:20.968717Z",
"shift_start_at": "2021-07-14T17:00:00Z",
"shift_end_at": "2021-07-14T19:00:00Z",
"spots": 1,
"shift_title": "Shift Title A",
"shift_description": null
},
"created_at": "2021-07-07T15:41:20.970080Z",
"status": 6, //Hours logged,
"logged_hours": 2.25,
"arrival_time": "2021-07-14T17:00:00Z",
"departure_time": "2021-07-14T19:00:00Z",
"hours_approved_by": {
"first_name": "Daniella",
"last_name": "Smith",
"email": "daniella_smith@domain.com"
},
"user": {
"id": "443f05ad-b1be-43bc-a213-3483471bc7fa",
"first_name": "Lela",
"last_name": "Craig",
"email": "Lela_craig@mailinator.com",
"gender": 1, //Female
"address": "3949 Decarie Boulevard, Montreal, QC, Canada",
"phone_number": "929384838",
"date_of_birth": "1973-03-04",
"timezone": "America/Toronto",
"address_coordinates": [
"45.5011136",
"-73.5793778"
]
},
"opportunity": {
"id": "14e21aad-869d-4384-be7b-e12cb8c0dc3d",
"category": {
"id": "9d20cefb-002a-42d9-bce4-9937dd8444b5",
"title": "Program ABC",
"description": "Description of Program ABC"
},
"title": "Transportation",
"description": "Description of transportation"
}
},
]
}
```
# Retrieve a reservation
This endpoint retrieves detailed information about a specific reservation by its ID. It provides a comprehensive view of the reservation’s associated shift, user, and opportunity details.
Endpoint
```
GET /api/reservations/{reservation_id}/
```
Replace `{`reservation\_id`}` with the actual ID of the reservation you wish to retrieve.
#### Example Request
```plaintext
GET /api/reservations/3b87b2ee-5063-471d-a70a-051d165ca1d0/
```
#### Authorization
Requests to this endpoint must include an `API-KEY` in the header for authentication:
```python
headers = {"API-KEY": "your_unique_api_key_here"}
response = requests.get("https://api.vomevolunteer.com/api/reservations/3b87b2ee-5063-471d-a70a-051d165ca1d0/", headers=headers)
```
#### Response Object
The response object includes comprehensive details about the user's profile:
```json
{
"id": "d20414eb-7c94-47a3-bcc3-4130aa74ce38",
"shift": {
"id": "645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"created_at": "2020-09-29T22:38:01.213771Z",
"shift_start_at": "2020-10-07T18:00:00Z",
"shift_end_at": "2020-10-07T20:00:00Z",
"spots": 10,
"shift_title": "Shift Title A",
"shift_description": null
},
"created_at": "2020-10-04T00:48:44.773601Z",
"status": 1, // Reserved
"logged_hours": 4.25,
"arrival_time": null,
"departure_time": null,
"hours_approved_by": {
"first_name": "Aaron",
"last_name": "Miller",
"email": "amiller@domain.com"
},
"user": {
"id": "874976ad-3bcc-456c-ad52-e54132b88571",
"first_name": "Daniel",
"last_name": "Smithkern",
"email": "sample123@domain.com",
"gender": 0, //Male
"address": "3949 Decarie Boulevard, Montreal, QC, Canada",
"phone_number": "1235474630",
"date_of_birth": "1975-02-08",
"timezone": "America/Detroit",
"address_coordinates": [
"45.4772493",
"-73.61535169999999"
]
},
"opportunity": {
"id": "a79d14ff-6611-4229-b244-f8151efd275f",
"category": {
"id": "51293d96-857b-455d-82ca-60c666bcda61",
"title": "Category A",
"description": "Help provide meal with a personal touch to the less privileged."
},
"title": "Opportunity A",
"description": "Helping 50,000 people get meals in our community with this program!"
}
}
```
# Search reservations
This endpoint allows for the efficient searching and filtering of reservation records based on specified query parameters such as email, first name, last name and other fields. It is designed to support operations that require accessing detailed reservation information quickly and effectively.
#### Endpoint and Usage:
* **Endpoint**: GET `/api/reservations/search/`
* **Base URL**: `https://api.vomevolunteer.com`
#### Query Parameters:
**Core Filters**
• **id (uuid)**: Filters reservations by the ID.
• **arrival\_time**: **(string)**: Filters reservations by arrival\_time.
• **depature\_time**: **(string)**: Filters reservations by the departure\_time.
• **status**: **(string)**: Filters reservations by the status.
• **created\_at**: **(string)**: Filters reservations by the **created\_at**.
* created\_at.gt (string, ISO-8601): Filters by created\_at > value (strictly after).
* created\_at.gte (string, ISO-8601): Filters by created\_at >= value.
* created\_at.lte (string, ISO-8601): Filters by created\_at <= value.
* created\_at.lt (string, ISO-8601): Filters by created\_at < value (strictly before).
**Reservation Statuses**
* `0`: Shift request pending
* `1`: Reserved
* `2`: Shift request declined
* `3`: Attendance confirmed
* `4`: Absent
* `5`: Checked-in
* `6`: Hours logged
* `7`: Hour claim pending
**Sample Requests**
# id
GET /api/reservations/search/?id=a31a7f99-87c2-4f13-af1e-502a724634d7
# arrival_time
GET /api/reservations/search/?arrival_time=2021-02-03T18:00:00Z
# departure_time
GET /api/reservations/search/?user.last_name=2021-02-03T19:00:00Z
# status
GET /api/reservations/search/?status=0
# created_at
GET /api/reservations/search/?created_at=2024-09-06T02:57:15.008656Z
# created_at.gt
GET /api/reservations/search/?created_at.gt=2024-09-06T02:57:15.008656Z
# created_at.gte
GET /api/reservations/search/?created_at.gte=2024-09-06T02:57:15.008656Z
# created_at.lt
GET /api/reservations/search/?created_at.lt=2024-09-06T02:57:15.008656Z
# created_at.lte
GET /api/reservations/search/?created_at.lte=2024-09-06T02:57:15.008656Z
**User Filters:**
• **user.email (string):** Filters reservations by the email associated with the user who made the reservation.
• **user.first\_name (string):** Filters reservations by the first name of the user.
• **user.last\_name (string)**: Filters reservations by the last name of the user.
**Sample Requests**
```markup
# enail
GET /api/reservations/search/?user.email=astrayuno@domain.com
# first_name
GET /api/reservations/search/?user.first_name=Astra
# last_name
GET /api/reservations/search/?user.last_name=Yuno
```
**Shift Filters:**
• **shift.id (uuid)**: Filters reservations by the ID of the associated shift.
• **shift.shift\_title (string)**: Filters reservations by the name of the associated shift.
#### Example Requests:
```http
# id
GET /api/reservations/search/?shift.id=a31a7f99-87c2-4f13-af1e-502a724634d7
# shift_title
GET /api/reservations/search/?shift.shift_title=title
# shift_start_at
GET /api/reservations/search/?shift.shift_start_at=2024-08-15T18:00:00Z
# shift_end_at
GET /api/reservations/search/?shift.shift_end_at=2024-10-15T18:00:00Z
# shift_start_at and shift_end_at
GET /api/reservations/search/?shift.shift_start_at=2024-08-15T18:00:00Z&shift.shift_end_at=2024-10-15T18:00:00Z
```
**Opportunity** **Filters**
**Search by opportunity filters:**
• **opportunity.id (uuid)**: Filters reservations by the ID of the associated opportunity.
• **opportunity.title (string)**: Filters reservations by the Title of the associated opportunity.
```http
# id
GET /ap i/reservations/search/?opportunity.id=a31a7f99-87c2-4f13-af1e-502a724634d7
# title
GET /api/reservations/search/?opportunity.title=SampleTitleA
```
#### Authorization:
Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/reservations/search/?email=user_email@domain.com", headers=headers)
```
#### Response Structure:
The response from this endpoint returns a list of reservations that match the query parameters, including detailed information about each reservation's associated shift and enrollment info.
#### Example Response Object:
```json
{
"count": 284,
"next": "https://api.vomevolunteer.com/api/reservations/search/?email=sample_volunteer_01%domain.com&page=2",
"previous": null,
"results":
[
{
"id": "8941d173-6909-45bd-a4d8-c13b11e170af",
"shift": {
"id": "c2e41a8a-c6fe-4468-bc86-8ec1af71ad12",
"created_at": "2020-10-27T10:17:52.450538Z",
"shift_start_at": "2020-11-05T13:00:00Z",
"shift_end_at": "2020-11-05T17:00:00Z",
"spots": 10,
"shift_title": null,
"shift_description": null
},
"created_at": "2020-11-05T02:55:28.030935Z",
"status": 0,
"logged_hours": 2.0,
"arrival_time": "2020-11-05T13:00:00Z",
"departure_time": "2020-11-05T14:00:00Z",
"hours_approved_by": null,
"user": {
"id": "874976ad-3bcc-456c-ad52-e54132b88571",
"first_name": "Daniel",
"last_name": "Smithkern",
"email": "sample_volunteer_05@domain.com",
"gender": 0,
"address": "3949 Decarie Boulevard, Montreal, QC, Canada",
"phone_number": "1235474630",
"date_of_birth": "1975-02-08",
"timezone": "America/Detroit",
"address_coordinates": [
"45.4772493",
"-73.61535169999999"
]
},
"opportunity": {
"id": "c3d92fa3-d904-4f9d-bb50-ec342a085931",
"category": {
"id": "b24e49fd-2b04-4b80-bf4f-871a4dc6ad3e",
"title": "Winter Food Program",
"description": "This program works to help alleviate hunger and the stigma of food insecurity in our students. By providing Weekends and More hampers to participating schools, staff and teachers can support students who are struggling with access to nutritious food on weekends. These hampers contain easy to prepare meals to meet the needs of students who would otherwise go without food when they are away from school meal programs."
},
"title": "Server",
"description": "We need help and looking for someone to serve food to homeless people!"
}
},
]
}
```
To format the JSON response structure without altering any content, organize it with clear headings and subheadings for each part. Here's a suggested format:
### Example Response Structure
#### Summary Information
* **Count**: 284
* **Next Page URL**: [URL for Page 2](https://api.vomevolunteer.com/api/reservations/search/?email=sample_volunteer_01%40mailinator.com\&page=2)
* **Previous Page URL**: null
For a complete description of each field in this response object, you can visit: [Reservations](/resources/editor-1)
# User Sequences
This object represents a user's assignment to a sequence. Once a user is assigned to a sequence, a user sequence object is created for it, and it allows Vome to track the status of the user's sequence.\
\
*For those not familiar with Vome's platform, a sequence is a custom step-by-step process for a user to complete. This is commonly a screening & onboarding process to track the completion of each step.*
**Endpoints**
* **GET** `/api/user-sequences/`
* **GET** `/api/user-sequences/{sequence_id}`
* **GET** `/api/user-sequences/search/`
# The User Sequence object
**Response Structure**:
#### Detailed Component Breakdown
**Sequence Object**
Each sequence object in the list includes comprehensive details about the user and the sequence:
* **id (**`string`**)**: Unique identifier for the relationship between the user and the sequence.
* [**user\_info**](#user-info-object) **(**`User Info Object`**)**: Contains details about the user associated with the sequence.
* [**sequence\_info**](#sequence-info-object) **(**`Sequence Info Object`**)**: Detailed information about the sequence.
* **status (**`string`**)**: Current status of the user in the sequence, including:
* **Active**: User is actively in this sequence.
* **Paused**: The user has been paused in this sequence.
* **Inactive**: The user is inactive in this sequence.
* **Finished**: The user has finished this sequence.
* **created\_at (**`string`**)**: Timestamp indicating when the user was added to the sequence.
* **updated\_at (**`string`**)**: Timestamp indicating the last update made to this user in the the sequence.
#### **User Info Object**
Provides information about the user associated with the sequence:
* **id (**`string`**)**: Unique identifier of the user.
* **first\_name (**`string`**)**: First name of the user.
* **last\_name (**`string`**)**: Last name of the user.
* **email (**`string`**)**: Email address of the user.
* **gender (**`integer | null`**)**: Gender of the user (if provided).
* `0` = Male
* `1` = Female
* `2` = Other
* `3` = User inputted they would rather not say
* **address (**`string`**)**: Complete address of the user.
* **phone\_number (**`string`**)**: Phone number of the user.
* **date\_of\_birth** `(string | null`**)**: Date of birth of the user.
* **timezone (string)**: Timezone of the user.
* **address\_coordinates** **(**`array | null`**)**: Geographic coordinates of the user if an address was address via Google Maps. If the address was added via the import process, this data would not be available.
#### **Sequence Info Object**
Detailed data about the sequence:
* **id (**`string`**)**: Unique identifier for the sequence.
* **title (**`string`**)**: Title of the sequence.
* **description (**`string`**)**: HTML content describing the sequence.
* **display\_status (**`string`**)**: Visibility status of the sequence (e.g., Public, Private).
* **Public**: The user is able to see they are in this sequence.
* **Private**: The user is unable to see they are in the sequence (it is only for admins to manage).
* [**step\_info** ](#step-info-object)**(array of Step Info Objects)**: Detailed steps included in the sequence.
#### Step Info Object
Each step within a sequence is detailed here:
* **step (integer)**: Sequential order number of the step.
* **type (integer)**: Type of step it is, including:
* `0` = Forms And Waiver
* `1` = Interview
* `2` = Training
* `3` = Orientation
* `4` = Custom
* `5` = Electronic Signature
* `6` = Form submission
* `7` = Video
* **step\_details (**`array)`: Depending on the type of step, it will include details about that step including the title, description, a file and other provide info by the organization.
* **id (**`string`**)**: identifier of the sequence step field, which can be used across multiple sequences.
* **title (**`string`**)**: Title of the sequence step field.
* **description (**`string`**)**: description of the sequence step field
* **user\_sequence\_info** (`Object`)
* *NOTE: If null, the user has no relationship with this step yet.*
* **id (**`string`**)**: identifier of the user's sequence step field.
* **status (**`integer`**)**: Title of the sequence step field.
* `0` = Added
* `1` = Completed
* **completion\_date (**`string`**)**: Timestamp indicating the date this sequence step was completed (if applicable).
* **expiration\_date (**`string`**)**: Timestamp indicating the date this sequence step expired (if applicable).
* **expiration\_date (**`string`**)**: Timestamp indicating the date this sequence step expired (if applicable).
* **attachment\_added** (`string`): URL to the file uploaded for this user's sequence step (if applicable).
[^1]:
# List all user sequences
This endpoint allows you to access a list of user sequences across the organization.
**Endpoint Description:**
* **Endpoint**: `GET /api/user-sequences/`
* **Base URL**: `https://api.vomevolunteer.com`
**Example Request:**
```
GET https://api.vomevolunteer.com/api/sequences/
```
**Authorization:**
Requests must include an API key in the header for authentication.
```json
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/form-submissions/", headers=headers)
```
**Response Structure**:
```json
{
"count": 49,
"next": "http://3.96.242.26:8030/api/user-sequences/?page=2",
"previous": null,
"results": [
{
"id": "4f02f472-2c15-436d-8a73-ff316cb9a78b",
"user_info": {
"id": "2c5f6853-7d10-427b-934b-1abc8d0ddcf1",
"first_name": "Bill",
"last_name": "Flood",
"email": "bill.flood@domain.com",
"gender": null,
"address": "",
"phone_number": "3343455454",
"date_of_birth": null,
"timezone": "America/Toronto",
"address_coordinates": null
},
"sequence_info": {
"id": "071ed9bf-ccce-4a31-9ce5-96fd6a0df0d9",
"title": "Sample Sequence Title",
"description": "
",
"user_sequence_info": {
"id": "892d267e-b337-4baa-b95e-90f59a61df40",
"status": 1,
"completion_date": "2024-10-10T08:03:58.176127Z",
"expiration_date": null,
"attachment_added": null
}
}
]
}
]
},
"status": "Active",
"created_at": "2024-10-10T08:03:23.530521Z",
"updated_at": "2024-10-10T08:03:58.998298Z"
},
]
}
```
**Response Structure:**
The API returns a list of user sequences along with pagination controls to navigate through large datasets effectively. Here’s a breakdown of the response structure and its components:
* **count (**`integer`**)**: Total number of sequences available.
* **next (**`string | null`**)**: URL to the next page of sequences, if available.
* **previous (**`string | null`**)**: URL to the previous page of sequences, if applicable.
* **results (**`array of User Sequence Objects`**)**: Contains detailed information about each sequence associated with a user.
# Retrieve a user sequence
This endpoint allows you to retrieve a specific user's sequence using the ID.
**Endpoint Description:**
* **Endpoint**: `GET GET /api/user-sequences/{sequence_id}/`
* **Base URL**: `https://api.vomevolunteer.com`
**Path Parameter:**
* **sequence\_id** (string): The unique identifier for the sequence to be retrieved.
**Example Request:**
```http
GET https://api.vomevolunteer.com/api/user-sequences/c306a611-4e8c-4b0c-852e-6d10b215b15a/
```
**Authorization:**
Requests must include an API key in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/user-sequences/c306a611-4e8c-4b0c-852e-6d10b215b15a/", headers=headers)
```
**Response Structure:**
The response from the API provides a detailed breakdown of the selected user sequence, including user information, sequence details, and step configurations.
**Example Response Object:**
```json
{
"id": "c306a611-4e8c-4b0c-852e-6d10b215b15a",
"user_info": {
"id": "46e199ee-20d9-4c53-8e73-2c81b84a4ea3",
"first_name": "Aaron",
"last_name": "Milkes",
"email": "aaron.mikes@domain.com",
"gender": 0,
"address": "1383 Décarie Street, Saint-Laurent, QC, Canada",
"phone_number": "4334322222",
"date_of_birth": "1985-02-06",
"timezone": "Canada/Central",
"address_coordinates": [
"45.5174791",
"-73.6872614"
]
},
"sequence_info": {
"id": "0a1c2932-83f7-4494-bd07-42b942bb0ffd",
"title": "New Sequence Created",
"description": "
para
",
"sequence_status": "Published",
"display_status": "Public",
"step_info": [
{
"step": 1,
"type": 3,
"orientation_details": [
{
"title": "Orientation A",
"description": "Description of step",
"user_orientation": {
"status": null,
"completion_on": null,
"expiration_on": null
}
}
]
},
{
"step": 2,
"type": 1,
"interview_details": [
{
"title": "Meeting with Supervisor",
"description": "You will need to book a session with us at www.vomevolunteer.com to slot yourself into the schedule",
"user_interview": {
"interview": null,
"status": null,
"completion_on": null,
"expiration_on": null
}
}
]
}
]
},
"status": "Finished",
"created_at": "2024-08-19T20:27:56.532350Z",
"updated_at": "2024-08-19T20:29:39.573290Z"
}
```
For a complete description of each field in this response object, you can visit: [User Sequences](/resources/editor-2)
# Search user sequences
This endpoint allows you to search through user sequences by specific criteria.
**Endpoint Description:**
* **Endpoint**: `GET /api/user-sequences/search/`
* **Base URL**: `https://api.vomevolunteer.com`
**Query Parameters:**
**Core Filters**
• **id (uuid)**: Filters user sequences by the ID.
• **created\_at (string)**: Filters user sequences by the **created\_at**.
**Sample Request:**
```http
# id
GET /api/user-sequences/search/?id==6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7
# created_at
GET /api/user-sequences/search/?created_at=2024-09-06T02:57:15.008656Z
```
**User Filters**
• **user.id (uuid)**: Filters user sequences by the ID.
• **user.first\_name (string)**: Filters user sequences by the **user's first name**.
• **user.last\_name (string)**: Filters user sequences by the **user's last name**.
• **user.email (string)**: Filters user sequences by the **user's email** .
• **created\_at**: **(string)**: Filters user sequences by **created\_at**.
* created\_at.gt (string, ISO-8601): Filters by created\_at > value (strictly after).
* created\_at.gte (string, ISO-8601): Filters by created\_at >= value.
* created\_at.lte (string, ISO-8601): Filters by created\_at <= value.
* created\_at.lt (string, ISO-8601): Filters by created\_at < value (strictly before).
**Sample Request:**
```
# id
GET /api/user-sequences/search/?user.id=6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7
# first_name
GET /api/user-sequences/search/?user.first_name=Aaron
# last_name
GET /api/user-sequences/search/?user.last_name=James
# email
GET //api/user-sequences/search/?user.email=sampleemail04@domain.com
# created_at
GET /api/user-sequences/search/?created_at=2024-09-06T02:57:15.008656Z
# created_at.gte
GET /api/user-sequences/search/?created_at.gte=2024-09-06T02:57:15.008656Z
# created_at.gt
GET /api/user-sequences/search/?created_at.gt=2024-09-06T02:57:15.008656Z
# created_at.lte
GET /api/user-sequences/search/?created_at.lte=2024-09-06T02:57:15.008656Z
# created_at.lt
GET /api/user-sequences/search/?created_at.lt=2026-09-06T02:57:15.008656Z
```
**Response Structure:**
The response includes a paginated list of user sequences matching the search criteria, providing comprehensive details about each sequence and associated user.
**Example Response Object:**
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/form-submissions/6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7", headers=headers)
```
```json
{
"count": 49,
"next": "http://3.96.242.26:8030/api/user-sequences/search/?first_name=Aaron&page=2",
"previous": null,
"results": [
{
"id": "4f02f472-2c15-436d-8a73-ff316cb9a78b",
"user_info": {
"id": "2c5f6853-7d10-427b-934b-1abc8d0ddcf1",
"first_name": "Bill",
"last_name": "Flood",
"email": "bill.flood@mailinator.com",
"gender": null,
"address": "",
"phone_number": "3343455454",
"date_of_birth": null,
"timezone": "America/Toronto",
"address_coordinates": null
},
"sequence_info": {
"id": "071ed9bf-ccce-4a31-9ce5-96fd6a0df0d9",
"title": "Sample Sequence Testing - 09",
"description": "
",
"user_sequence_info": {
"id": "892d267e-b337-4baa-b95e-90f59a61df40",
"status": 1,
"completion_date": "2024-10-10T08:03:58.176127Z",
"expiration_date": null,
"attachment_added": null
}
}
]
}
]
},
"status": "Active",
"created_at": "2024-10-10T08:03:23.530521Z",
"updated_at": "2024-10-10T08:03:58.998298Z"
},
]
}
```
# Form Submissions
When an organization creates a form on Vome, and the user submits the form, it creates a form submission object. \
\
The form submission includes detailed information about the content of the form submission, for example, answers to questions provided, whether shifts were requested on it, which form it is linked to, and so forth.
**Endpoints**
* **GET** `/api/form-submissions/`
* **GET** `/api/form-submissions/{submission_id}/`
* **GET** `/api/form-submissions/search/`
# The Form Submission object
{% code overflow="wrap" %}
```json
{
"id": "60c5e52b-e680-4b62-adc1-207e4ced130f",
"user": {
"id": "443f05ad-b1be-43bc-a213-3483471bc7fa",
"first_name": "Lara",
"last_name": "Smith",
"email": "lara_smith@domain.com",
"gender": 0,
"address": "2934 Thurlow Road, Hampstead, Montreal, QC, Canada",
"phone_number": "929384838",
"date_of_birth": "1973-03-04",
"timezone": "America/Toronto",
"address_coordinates": [
"45.4787326",
"-73.6406602"
]
},
"submission_status": "New",
"created_at": "2024-10-30T21:19:53.069586Z",
"sites": [
{
"id": "f3277763-8f13-43a1-9276-358d810d2a9b",
"title": "Site A"
}
],
"categories": [
{
"id": "65e619c4-94a8-4259-877d-ecc0ca3c0822",
"title": "Events & Prizes"
},
]
},
"arrival_source": {
"id": "182e2f04-0d3c-4637-89a7-c6dbae95e90f",
"category": {
"id": "c82cd6c8-0b5a-48af-853d-0a57e6954969",
"title": "Title of Category A",
"description": "Description of Category A"
},
"title": "Opportunity Title A",
"description": "Description of Title A"
},
"questions": [
{
"id": "6d51d684-70a0-4d3e-a5ef-db61025e03de",
"question": {
"id": "d56d80ac-7665-49bd-b7f1-ddd6873377bd",
"title": "If applicable, describe your previously involvement here.",
"question_type": 0,
"options": []
},
"answer": "",
"options": [],
"responded": false
},
{
"id": "24fec7ab-b5a6-4803-9f92-73e2aa9983d3",
"question": {
"id": "c9cf2681-17e0-4924-a1ae-97af4315d335",
"title": "Decide the necessary percentages here?",
"question_type": 10,
"options": [
"Trees",
"Forest",
"Water"
],
"allocation_input_type": 1,
"allocation_total": "100.0000",
"allocation_decimal_places": 2
},
"answer": "",
"options": [],
"date": null,
"responded": true,
"allocation_values": {
"Trees": "10.00",
"Forest": "70.00",
"Water": "20.00"
},
"auto_populated_lists": []
},
{
"id": "70893686-0feb-421a-9808-212191799ed8",
"question": {
"id": "8edd39f0-a30d-4952-90ff-1b8cd1fff550",
"title": "What opportunities are you interested in?",
"question_type": 11,
"options": []
},
"answer": "",
"options": [],
"date": null,
"responded": true,
"allocation_values": null,
"auto_populated_lists": [
{
"id": "a79d14ff-6611-4229-b244-f8151efd275f",
"title": "12-h volunteers"
},
{
"id": "53fb7d1c-11c0-41af-bad0-be0962588cf8",
"title": "Administrator"
}
]
},
{
"id": "24666398-306d-4058-a058-50364af12c06",
"question": {
"id": "3a25e1ab-fb49-49d1-ab6a-690e03e5a5cd",
"title": "Which days of the week would you like to join us?",
"question_type": "Checkbox",
"options": [
"Thursday",
"Tuesday/Thurs",
"Friday"
]
},
"answer": "",
"options": [
"Friday"
],
"responded": true
}
],
"medical_info": null,
"emergency_contact": {
"name": "Daniel",
"relationship": "Dad",
"phone_number": "9389393898"
},
"digital_consent": [
{
"id": "dc6a12a3-10da-49b7-bdf9-51514439f063",
"digital_consent_info": null,
"consent_status": 3 //Not provided
}
],
"general_availability": [
{
"id": "7b8cca42-fcfd-4566-9715-7a9ec57132bf",
"day": 2, //Tuesday
"availability": "Morning"
}
],
"attachments": [
{
"id": "6c93e611-7e06-4aeb-9e30-fdad10126c2b",
"document_file": null,
"notes": "",
"attachment_info": {
"id": "854c5709-af07-49bd-b653-6a17154d192e",
"title": "Drivers License",
"description": ""
}
}
],
"opportunities": [
{
"opportunity": {
"id": "6dd9de34-eee5-48dc-a684-edef63f7cd61",
"category": {
"id": "c82cd6c8-0b5a-48af-853d-0a57e6954969",
"title": "Category Title A",
"description": "Description of Category Title A"
},
"title": "Opportunity Title A",
"description": "Description of Opportunity Title A"
},
"opportunity_shifts_count": 1
},
],
"folder": {
"name": "Basketball Program"
},
"form": {
"id": "b4078162-9d3c-41fa-abbb-aada180c87d5",
"title": "Form Title A"
}
}
```
{% endcode %}
#### **Components of the Submission Detail Objects**
Each submission detail object provides comprehensive data related to a specific form submission by a user, which includes:
* **id (**`string`**)**: A unique identifier for the form submission.
* [**user** ](#user-object)**(**`User` `Object`**)**: Details of the user who made the submission.
* **submission\_status (**`string`**)**: Status of the submission (e.g., New, Reviewed), including:
* **New**: Initial status for a form submission.
* **In Review**: Submission is currently being reviewed.
* **Reviewed**: Submission has been reviewed.
* **Rejected**: Submission has been rejected.
* **Completed**: Submission process is completed.
* **created\_at (**`string`**)**: Timestamp indicating when the form was submitted.
* [**arrival\_source** ](#arrival-source-array)(`Arrival Source Array`)
* [**questions**](#questions-array) **(**`Questions Array)`: A collection of questions and responses included in the submission.
* [**medical\_info**](#medical-information-object) **(**`Medical Information Object)`: Basic medical information provided in the submission added by the user.
* [**emergency\_contact**](#emergency-contact-object) **(**`Emergency Contact Object`**)**: Emergency contact details provided by the user.
* [**digital\_consent** ](#digital-consent-array)**(**`Consent Array`**)**: Tracks digital consent provided by the user.
* [**general\_availability**](#availability-array) **(**`Availability Array`**)**: General availability time slots, including days of the week coupled with the time of day (i.e. morning, afternoon, evening or a custom time slot provided by the user).
* [**attachments**](#attachments-array) **(**`Attachments Array`**)**: Any files or documents attached to the submission as part of an attachments field.
* [**opportunity**](#opportunity-array) **(**`Opportunity Array`**)**: Opportunities relating to shifts that were associated with the submission, if any.
* [**folder** ](#folder-object)**(**`Form Object`**)**: The folder related to the form which was submitted by the user.
* [**form**](#form-object) **(**`Form Object`**)**: Information about the form that was submitted, including the ID and title.
* [**auto\_populated\_lists**](#auto-populated-lists-object-auto_populated_lists) (Auto-Populated Lists Object): Server-provided option lists used to render Powered Select UI (opportunities, sites, and categories).
* **allocation\_values** is the parsed JSON map of answers for allocation questions (question\_type = 10).
* Key: each allocation option label (from question.options)
* Value: the entered amount as a string (for example ["25.00"](app://-/index.html#))
\
**Detailed Component Structures**
#### **User Object**
Comprehensive details about the user's profile information.
* **id (**`string`**)**: Unique identifier for the user.
* **first\_name**, **last\_name**, **full\_name** (`string`): The name of the user.
* **email** (`string`): Email address of the user.
* **gender** (`string` | `null`): The gender of the user. \
\
`0` = Male\
`1` = Female\
`2` = Other\
`3` = User inputted they would rather not say
* **address** (`string`): The complete address of the user.
* **phone\_number** (`string`): Phone number of the user.
* **date\_of\_birth** (`string` | `null`): The date of birth of the user.
* **address\_coordinates** (`array`): Geographic coordinates of the user if an address was address via Google Maps. If the address was added via the import process, this data would not be available.
#### **Arrival Source Array**
In some circumstances, a user may be redirected to submit a form when trying to apply for an opportunity. When this occurs, we indicate the opportunity for which the user arrived from.
* **id (string)**: Identifier of the opportunity for which the user arrived from when submitting this form.
* **title** (`string`): Title of the opportunity.
* **description** (`string`): description of the opportunity.
* **category** (**category Object**): Includes the categories related to the opportunity
* **id** (`string`): Identifier of the category.
* **title** (`string`): Title of the category.
#### **Questions Array**
Each entry in this array represents a question and its respective answer:
* **id (**`string`**)**: Identifier for the question within the form.
* [**question** ](#question-object)**(**`Question Object`**)**: Details of the question, including the title, type and options available.
* **answer (**string**)**: The answer provided by the user (if the question type is not a single or multiple selection).
* **options (**`array`**)**: The answer provided by the user (if the question type is a *single or multiple selection field).*
* **responded (**`boolean`**)**: Indicates whether the question was answered by the user.
#### **Question Object**
* **id (**`sting`**):** Identifier for the question, which can be used across multiple forms.
* **title (**`string`**)**: The text of the question.
* **type (**`integer`**)**: Represents the type of question, including:
* `0`: Text
* `1`: Single Selection
* `2`: Multiple Selection
* `3`: Date
* `4`: Timeslot
* `5`: Address
* `6`: Number
* `7`: Email
* `8`: Website
* `9`: Boolean
* 10: Allocation
* 11: Powered Select
* **options (**`array`**)**: Any selectable options associated with the question. *Only applicable for single or multiple selection fields.*
* **`allocation_input_type`** (integer): controls the unit expected for each value in allocation\_values all supported types include:
* 0 : Percent
* 1 : Number
* **`allocation_total`** (string decimal): The required sum of all allocation entries for the question (for example, `"100.0000"`).
* **`allocation_decimal_places`** (integer): Maximum number of decimal places allowed per allocation entry (for example, `2` allows `10.25` but not `10.257`)
***
#### **Medical Information Object**
* **description (**`string`**)**: Description of any medical information provided by the user.
* **has\_medical\_info (**`boolean`**)**: Indicates whether there is any medical information inputted for this user.
#### **Emergency Contact Object**
* **name (**`string`**)**: The name of the emergency contact.
* **phone\_number (**`string`**)**: The phone number of the emergency contact.
* **relationship (**`string`**)**: The relationship of the contact to the user.
#### **Digital Consent Array**
This array contains details about the digital consent provided by the user:
* **id (**`string`**)**: Unique identifier for the consent entry.
* **digital\_consent\_info (`integer`)**: Includes the information created by the organization regarding the type of consent requested.
* **consent\_status (`integer`)**: Indicates whether consent was provided or not.
* `0`: Typed
* `1`: Uploaded
* `2`: Not responded
#### **Emergency Contact Object**
* **name (**`string`**)**: The name of the emergency contact.
* **phone\_number (**`string`**)**: The phone number of the emergency contact.
* **relationship (**`string`**)**: The relationship of the contact to the user.
#### **Availability Array**
Outlines the general availability inputted by the user on this form:
* **id (**`string`**)**: Identifier for the availability entry of the user's form.
* **day (**`integer`**)**: Day of the week represented numerically.
* `0`: Sunday
* `1`: Monday
* `2`: Tuesday
* `3`: Wednesday
* `4`: Thursday
* `5`: Friday
* `6`: Saturday
* **availability (**`string`**)**: Description of the availability (e.g., Morning, Afternoon, Evening or Custom time slot).
#### **Attachments Array**
Details of documents attached to the form by the user:
* **id (**`string`**)**: Unique identifier for the attachment on the form.
* **document\_file (**`string`**)**: URL of the attached document by the user
* **attachment\_info (**`Object`**)**: Details about the attachment requested by the admin including the ID, title and description shown to users.
* **id (**`string`**)**: Unique identifier for the attachment, which can be used across many forms.
* **title (**`string`**)**: title of the attachment field added by the organization.
* **description (**`Object`**)**: description of the attachment field added by the organization.
#### **Opportunity Array**
If a user submits the form and includes shifts on it, we provide a list of the opportunities related to the the shift along with the count of the number of shifts submitted for it.
* **id** (`string`): Identifier of the opportunity.
* **title** (`string`): Title of the opportunity.
* **description** (`string`): Description of the opportunity.
* **opportunity\_shifts\_count** (`string`): Number of requested shifts included on the form submission for that opportunity.
* **category** (**Category Object**): Details of the related category to this opportunity
* **id** (`string`): Identifier of the category.
* **title** (`string`): Title of the category.
* **description** (`string`): Description of the category.
#### Folder Object
* **name** (`string`): Name of folder related to the form which was submitted by the user
#### **Form** Object
Details of the form submitted:
* **id (string)**: Unique identifier for the form which was submitted .
* **title (string)**: The title of the form which was submitted
#### **Auto-Populated Lists Object (auto\_populated\_lists)**
* categories (array of {id, title}): List of available Opportunities (categories).
* sites (array of {id, title}): List of available Organization Sites.
* opportunities (array of {id, title}): List of available Opportunity Roles (position titles).
# List all form submissions
This endpoint provides a comprehensive list of form submissions, including detailed insights into what a user responded to a Vome form.
#### **Endpoint and Request Method**:
* **GET** `/api/form-submissions/`
* Access this endpoint to retrieve a paginated list of form submissions along with associated details.
1. **Example Request**:
* `GET https://api.vomevolunteer.com/api/form-submissions/`
2. **Authorization**:
* Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/form-submissions/", headers=headers)
```
**Response Structure**:
The response provides a summary count and pagination details along with an array of submission records. Each record includes user information, submission status, question responses, consent details, availability, and any attachments.
**Form Submissions Object Structure**
* **count (**`integer`**)**: Indicates the total number of form submissions available.
* **next (**`string | null`**)**: Provides the URL to the next page of form submissions if more pages are available.
* **previous (**`string | null`**)**: Provides the URL to the previous page of form submissions if applicable.
* **results (**`array of Submission Detail Objects`**)**: Contains detailed information for each form submission entry.
# Retrieve a form submission
This endpoint provides a way to retrieve a specific form submission using the form submission ID.
**Endpoint Description:**
* **Endpoint**: `GET /api/form-submissions/{submission_id}/`
* **Base URL**: `https://api.vomevolunteer.com`
**Path Parameter:**
* **submission\_id** (string): The unique identifier for the form submission to be retrieved.
**Example Request:**
```http
GET https://api.vomevolunteer.com/api/form-submissions/6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7/
```
**Authorization:**
Requests must include an API key in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/form-submissions/6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7", headers=headers)
```
```json
{
"id": "60c5e52b-e680-4b62-adc1-207e4ced130f",
"user": {
"id": "443f05ad-b1be-43bc-a213-3483471bc7fa",
"first_name": "Lara",
"last_name": "Smith",
"email": "lara_smith@domain.com",
"gender": 0,
"address": "2934 Thurlow Road, Hampstead, Montreal, QC, Canada",
"phone_number": "929384838",
"date_of_birth": "1973-03-04",
"timezone": "America/Toronto",
"address_coordinates": [
"45.4787326",
"-73.6406602"
]
},
"submission_status": "New",
"created_at": "2024-10-30T21:19:53.069586Z",
"sites": [
{
"id": "f3277763-8f13-43a1-9276-358d810d2a9b",
"title": "Site A"
}
],
"categories": [
{
"id": "65e619c4-94a8-4259-877d-ecc0ca3c0822",
"title": "Events & Prizes"
},
]
},
"arrival_source": {
"id": "182e2f04-0d3c-4637-89a7-c6dbae95e90f",
"category": {
"id": "c82cd6c8-0b5a-48af-853d-0a57e6954969",
"title": "Title of Category A",
"description": "Description of Category A"
},
"title": "Opportunity Title A",
"description": "Description of Title A"
},
"questions": [
{
"id": "6d51d684-70a0-4d3e-a5ef-db61025e03de",
"question": {
"id": "d56d80ac-7665-49bd-b7f1-ddd6873377bd",
"title": "If applicable, describe your previously involvement here.",
"question_type": 0,
"options": []
},
"answer": "",
"options": [],
"responded": false
},
{
"id": "24fec7ab-b5a6-4803-9f92-73e2aa9983d3",
"question": {
"id": "c9cf2681-17e0-4924-a1ae-97af4315d335",
"title": "Decide the necessary percentages here?",
"question_type": 10,
"options": [
"Trees",
"Forest",
"Water"
],
"allocation_input_type": 1,
"allocation_total": "100.0000",
"allocation_decimal_places": 2
},
"answer": "",
"options": [],
"date": null,
"responded": true,
"allocation_values": {
"Trees": "10.00",
"Forest": "70.00",
"Water": "20.00"
},
"auto_populated_lists": []
},
{
"id": "70893686-0feb-421a-9808-212191799ed8",
"question": {
"id": "8edd39f0-a30d-4952-90ff-1b8cd1fff550",
"title": "What opportunities are you interested in?",
"question_type": 11,
"options": []
},
"answer": "",
"options": [],
"date": null,
"responded": true,
"allocation_values": null,
"auto_populated_lists": [
{
"id": "a79d14ff-6611-4229-b244-f8151efd275f",
"title": "12-h volunteers"
},
{
"id": "53fb7d1c-11c0-41af-bad0-be0962588cf8",
"title": "Administrator"
}
]
},
{
"id": "24666398-306d-4058-a058-50364af12c06",
"question": {
"id": "3a25e1ab-fb49-49d1-ab6a-690e03e5a5cd",
"title": "Which days of the week would you like to join us?",
"question_type": "Checkbox",
"options": [
"Thursday",
"Tuesday/Thurs",
"Friday"
]
},
"answer": "",
"options": [
"Friday"
],
"responded": true
}
],
"medical_info": null,
"emergency_contact": {
"name": "Daniel",
"relationship": "Dad",
"phone_number": "9389393898"
},
"digital_consent": [
{
"id": "dc6a12a3-10da-49b7-bdf9-51514439f063",
"digital_consent_info": null,
"consent_status": 3 //Not provided
}
],
"general_availability": [
{
"id": "7b8cca42-fcfd-4566-9715-7a9ec57132bf",
"day": 2, //Tuesday
"availability": "Morning"
}
],
"attachments": [
{
"id": "6c93e611-7e06-4aeb-9e30-fdad10126c2b",
"document_file": null,
"notes": "",
"attachment_info": {
"id": "854c5709-af07-49bd-b653-6a17154d192e",
"title": "Drivers License",
"description": ""
}
}
],
"opportunities": [
{
"opportunity": {
"id": "6dd9de34-eee5-48dc-a684-edef63f7cd61",
"category": {
"id": "c82cd6c8-0b5a-48af-853d-0a57e6954969",
"title": "Category Title A",
"description": "Description of Category Title A"
},
"title": "Opportunity Title A",
"description": "Description of Opportunity Title A"
},
"opportunity_shifts_count": 1
},
],
"folder": {
"name": "Basketball Program"
},
"form": {
"id": "b4078162-9d3c-41fa-abbb-aada180c87d5",
"title": "Form Title A"
}
}
```
# Search form submissions
This endpoint allows you to query and retrieve form submissions based on user-specified criteria such as an email address or an answer to a question. This functionality is essential for filtering and efficiently managing large datasets of form submissions.
**Endpoint Description:**
* **Endpoint**: `GET /api/form-submissions/`
* **Base URL**: `https://api.vomevolunteer.com`
#### Query Parameters:
**Core Filters**
• **id (uuid)**: Filters form submissions by the ID.
* **created\_at (string)**: Filters form submissions by the **created\_at**.
* created\_at.gt (string, ISO-8601): Filters by created\_at > value (strictly after).
* created\_at.gte (string, ISO-8601): Filters by created\_at >= value.
* created\_at.lte (string, ISO-8601): Filters by created\_at <= value.
* created\_at.lt (string, ISO-8601): Filters by created\_at < value (strictly before).
# id
GET /api/form-submissions/search/?id=6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7
# created_at
GET /api/form-submissions/search/?created_at=2024-09-06T02:57:15.008656Z
# created_at.gte
GET /api/form-submissions/search/?created_at.gte=2024-09-06T02:57:15.008656Z
# created_at.gt
GET /api/form-submissions/search/?created_at.gt=2024-09-06T02:57:15.008656Z
# created_at.lte
GET /api/form-submissions/search/?created_at.lte=2024-09-06T02:57:15.008656Z
# created_at.lt
GET /api/form-submissions/search/?created_at.lt=2026-09-06T02:57:15.008656Z
\
**Question filters**
• **question.id (string)**: Filters form submissions by the question ID.
• **question.answer (string)**: Filters form submissions by the answers
GET /api/form-submissions/search/?question.id=6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7&answer=NO
**User Filters**
• **user.id (uuid)**: Filters form submissions by the ID.
• **user.first\_name**: **(string)**: Filters form submissions by the user's first name.
• **user.last\_name**: **(string)**: Filters form submissions by the user's last name.
• **user.email** (**string**): Searches for form submissions associated with a specific email address.
# id
GET /api/form-submissions/search/?user.id=6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7
# first_name
GET /api/form-submissions/search/?user.first_name=Aaron
# last_name
GET /api/form-submissions/search/?user.last_name=James
# email
GET /api/form-submissions/search/?user.email=sample_volunteer_04@domain.com
**Form filters**
• **form.id:** Filters form submissions by the form ID.
• **form.title:** Filters form submissions by the form title.
**Sample Request:**
# id
GET /api/form-submissions/search/?form.id=6e84d2e9-ceb2-4b58-9bfb-97f49dd267e7
# title
GET /api/form-submissions/search/?form.title=Form
# title (with spaces)
GET /api/form-submissions/search/?form.title=New+Form+Application
**Folder filters**
• **folder.name:** Filters form submissions by the folder name.
**Sample Request:**
```
# folder
GET /api/form-submissions/search/?folder.name=Folder
# folder (with spaces)
GET /api/form-submissions/search/?folder.name=Folder+Name
```
**Authorization:**
Requests must include an API key in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/form-submissions/?email=sample_volunteer_04@mailinator.com", headers=headers)
```
**Response Structure:**
**Example Response Object:**
```json
{
"count": 848,
"next": "https://api.vomevolunteer.com/api/form-submissions/?page=2",
"previous": null,
"results": [
{
"id": "60c5e52b-e680-4b62-adc1-207e4ced130f",
"user": {
"id": "443f05ad-b1be-43bc-a213-3483471bc7fa",
"first_name": "Lara",
"last_name": "Smith",
"email": "lara_smith@domain.com",
"gender": 0,
"address": "2934 Thurlow Road, Hampstead, Montreal, QC, Canada",
"phone_number": "929384838",
"date_of_birth": "1973-03-04",
"timezone": "America/Toronto",
"address_coordinates": [
"45.4787326",
"-73.6406602"
]
},
"submission_status": "New",
"created_at": "2024-10-30T21:19:53.069586Z",
"sites": [
{
"id": "f3277763-8f13-43a1-9276-358d810d2a9b",
"title": "Site A"
}
],
"categories": [
{
"id": "65e619c4-94a8-4259-877d-ecc0ca3c0822",
"title": "Events & Prizes"
},
]
},
"arrival_source": {
"id": "182e2f04-0d3c-4637-89a7-c6dbae95e90f",
"category": {
"id": "c82cd6c8-0b5a-48af-853d-0a57e6954969",
"title": "Title of Category A",
"description": "Description of Category A"
},
"title": "Opportunity Title A",
"description": "Description of Title A"
},
"questions": [
{
"id": "6d51d684-70a0-4d3e-a5ef-db61025e03de",
"question": {
"id": "d56d80ac-7665-49bd-b7f1-ddd6873377bd",
"title": "If applicable, describe your previously involvement here.",
"question_type": 0,
"options": []
},
"answer": "",
"options": [],
"responded": false
},
{
"id": "24fec7ab-b5a6-4803-9f92-73e2aa9983d3",
"question": {
"id": "c9cf2681-17e0-4924-a1ae-97af4315d335",
"title": "Decide the necessary percentages here?",
"question_type": 10,
"options": [
"Trees",
"Forest",
"Water"
],
"allocation_input_type": 1,
"allocation_total": "100.0000",
"allocation_decimal_places": 2
},
"answer": "",
"options": [],
"date": null,
"responded": true,
"allocation_values": {
"Trees": "10.00",
"Forest": "70.00",
"Water": "20.00"
},
"auto_populated_lists": []
},
{
"id": "70893686-0feb-421a-9808-212191799ed8",
"question": {
"id": "8edd39f0-a30d-4952-90ff-1b8cd1fff550",
"title": "What opportunities are you interested in?",
"question_type": 11,
"options": []
},
"answer": "",
"options": [],
"date": null,
"responded": true,
"allocation_values": null,
"auto_populated_lists": [
{
"id": "a79d14ff-6611-4229-b244-f8151efd275f",
"title": "12-h volunteers"
},
{
"id": "53fb7d1c-11c0-41af-bad0-be0962588cf8",
"title": "Administrator"
}
]
},
{
"id": "24666398-306d-4058-a058-50364af12c06",
"question": {
"id": "3a25e1ab-fb49-49d1-ab6a-690e03e5a5cd",
"title": "Which days of the week would you like to join us?",
"question_type": "Checkbox",
"options": [
"Thursday",
"Tuesday/Thurs",
"Friday"
]
},
"answer": "",
"options": [
"Friday"
],
"responded": true
}
],
"medical_info": null,
"emergency_contact": {
"name": "Daniel",
"relationship": "Dad",
"phone_number": "9389393898"
},
"digital_consent": [
{
"id": "dc6a12a3-10da-49b7-bdf9-51514439f063",
"digital_consent_info": null,
"consent_status": 3 //Not provided
}
],
"general_availability": [
{
"id": "7b8cca42-fcfd-4566-9715-7a9ec57132bf",
"day": 2, //Tuesday
"availability": "Morning"
}
],
"attachments": [
{
"id": "6c93e611-7e06-4aeb-9e30-fdad10126c2b",
"document_file": null,
"notes": "",
"attachment_info": {
"id": "854c5709-af07-49bd-b653-6a17154d192e",
"title": "Drivers License",
"description": ""
}
}
],
"opportunities": [
{
"opportunity": {
"id": "6dd9de34-eee5-48dc-a684-edef63f7cd61",
"category": {
"id": "c82cd6c8-0b5a-48af-853d-0a57e6954969",
"title": "Category Title A",
"description": "Description of Category Title A"
},
"title": "Opportunity Title A",
"description": "Description of Opportunity Title A"
},
"opportunity_shifts_count": 1
},
],
"folder": {
"name": "Basketball Program"
},
"form": {
"id": "b4078162-9d3c-41fa-abbb-aada180c87d5",
"title": "Form Title A"
}
}
]
}
```
# Shifts
This object represents a shift within your organization. A shift belongs to an opportunity, and each opportunity can have one or more shifts attached to it. For example, a "Weekend Mentor" opportunity may contain shifts like "Morning Shift" and "Afternoon Shift".
Each shift stores the key details used to describe and schedule it, including its title, description, start time, end time, capacity, related opportunity, derived location, and public share URL.
You can use the Shifts API to list all shifts for your institution, retrieve a single shift by ID, or search shifts using filters such as title, date, start time, end time, spots, opportunity, category, and created date.
### Endpoints
* `GET /api/shifts/`
* `GET /api/shifts/{shift_id}/`
* `GET /api/shifts/search/`
# The Shift Object
This object represents a scheduled shift attached to an opportunity. A shift stores the schedule, capacity, and share link used to publish or manage a specific time slot.
Response Object:
```json
{
"id": "645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"created_at": "2026-02-05T07:40:29.324645Z",
"shift_start_at": "2026-02-12T09:00:00Z",
"shift_end_at": "2026-02-12T13:00:00Z",
"spots": 10,
"spots_reserved": 4,
"spots_available": 6,
"opportunity": {
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-02T10:15:00Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
},
"shift_location": "123 Main Street",
"shift_title": "Morning Shift",
"shift_description": "Support setup and check-in.",
"share_shift_url": "https://api.vomevolunteer.com/api/share/shift/645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"title": "Morning Shift",
"description": "Support setup and check-in."
}
```
Response Object:
* `id`: The unique UUID of the shift.
* `created_at`: The timestamp when the shift was created.
* `shift_start_at`: The scheduled start date and time of the shift.
* `shift_end_at`: The scheduled end date and time of the shift.
* `spots`: The total number of spots available on the shift.
* `spots_reserved`: The number of filled spots currently counted on the shift.
* `spots_available`: The number of remaining available spots.
* `opportunity`**:** Details about the associated opportunity to this shift, including
* `id` (`string`): Identifier of the opportunity.
* `title` (`string`): Title of the opportunity.
* `description`(`string`): Description of the opportunity.
* `share_opportunity_url`: A public-facing share link for the opportunity.
* `category` **:** Details of the related category to this opportunity
* `id` (`string`): Identifier of the category.
* `title` (`string`): Title of the category.
* `description` (`string`): Description of the category.
* `shift_location`: A derived display location for the shift.
* `shift_title`: The stored title of the shift.
* `shift_description`: The stored description of the shift.
* `share_shift_url`: A public-facing share link for the shift.
* `title`: A convenience alias of `shift_title`.
* `description`: A convenience alias of `shift_description`.
# List all Shifts
Endpoint and Request Method:
`GET /api/shifts/`
This endpoint retrieves a paginated list of all shifts for the authenticated institution.
Example Request:
`GET https://api.vomevolunteer.com/api/shifts/`
Authorization:
Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get(
"https://api.vomevolunteer.com/api/shifts/",
headers=headers
)
```
Supported query parameters:
* `page`: Page number.
* `page_size`: Number of results per page, up to `100`.
* `opportunity.id`: Filters by related opportunity ID.
* `opportunity_id`: Alias for `opportunity.id`.
* `opportunity_role_id`: Alias for `opportunity.id`.
* `category.id`: Filters by related category ID.
* `category_id`: Alias for `category.id`.
Response Structure:
The response is a paginated object containing shift records. Each record represents a single shift along with its schedule, capacity details, and share URL.
Response Object:
```json
{
"count": 2,
"next": "https://api.vomevolunteer.com/api/shifts/?page=2",
"previous": null,
"results": [
{
"id": "645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"created_at": "2026-02-05T07:40:29.324645Z",
"shift_start_at": "2026-02-12T09:00:00Z",
"shift_end_at": "2026-02-12T13:00:00Z",
"spots": 10,
"spots_reserved": 4,
"spots_available": 6,
"opportunity": {
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-02T10:15:00Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
},
"shift_location": "123 Main Street",
"shift_title": "Morning Shift",
"shift_description": "Support setup and check-in.",
"share_shift_url": "https://api.vomevolunteer.com/api/share/shift/645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"title": "Morning Shift",
"description": "Support setup and check-in."
},
{
"id": "645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"created_at": "2026-02-05T07:40:29.324645Z",
"shift_start_at": "2026-02-12T09:00:00Z",
"shift_end_at": "2026-02-12T13:00:00Z",
"spots": 10,
"spots_reserved": 4,
"spots_available": 6,
"opportunity": {
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-02T10:15:00Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
},
"shift_location": "123 Main Street",
"shift_title": "Morning Shift",
"shift_description": "Support setup and check-in.",
"share_shift_url": "https://api.vomevolunteer.com/api/share/shift/645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"title": "Morning Shift",
"description": "Support setup and check-in."
},
]
}
```
# Retrieve a Shift
Endpoint
`GET /api/shifts/{shift_id}/`
Replace `{shift_id}` with the actual ID of the shift you wish to retrieve.
Example Request
`GET /api/shifts/645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d/`
Authorization
Requests to this endpoint must include an `API-KEY` in the header for authentication:
```python
headers = {"API-KEY": "your_unique_api_key_here"}
response = requests.get(
"https://api.vomevolunteer.com/api/shifts/645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d/",
headers=headers
)
```
Response Object
The response object includes details about a single shift, including timing, spot counts, and share URL:
```json
{
"id": "645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"created_at": "2026-02-05T07:40:29.324645Z",
"shift_start_at": "2026-02-12T09:00:00Z",
"shift_end_at": "2026-02-12T13:00:00Z",
"spots": 10,
"spots_reserved": 4,
"spots_available": 6,
"opportunity": {
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-02T10:15:00Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
},
"shift_location": "123 Main Street",
"shift_title": "Morning Shift",
"shift_description": "Support setup and check-in.",
"share_shift_url": "https://api.vomevolunteer.com/api/share/shift/645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"title": "Morning Shift",
"description": "Support setup and check-in."
}
```
Common errors:
* `404 Not Found`: The shift does not exist, or it does not belong to the authenticated institution.
Example:
```json
{
"detail": "Not found."
}
```
# Search Shifts
This endpoint allows for the efficient searching and filtering of shift records based on specified query parameters such as title, timing, capacity, opportunity, category, and created date. It is designed to support operations that require accessing detailed shift information quickly and effectively.
Endpoint and Usage:
Endpoint: `GET /api/shifts/search/`
Base URL: `https://api.vomevolunteer.com`
Query Parameters:
Core Filters
* `id` (uuid): Filters shifts by ID.
* `title` (string): Filters shifts by title.
* `shift_title` (string): Alias for `title`.
* `description` (string): Filters shifts by description.
* `shift_description` (string): Alias for `description`.
* `created_at` (string, ISO-8601): Filters shifts by exact `created_at`.
* `created_at.gt` (string, ISO-8601): Filters by `created_at > value`.
* `created_at.gte` (string, ISO-8601): Filters by `created_at >= value`.
* `created_at.lte` (string, ISO-8601): Filters by `created_at <= value`.
* `created_at.lt` (string, ISO-8601): Filters by `created_at < value`.
* `created_date` (string, ISO-8601 date): Filters by the date portion of `created_at`.
* `created_on` (string, ISO-8601 date): Alias for `created_date`.
* `created_date.gt` / `created_on.gt`: Filters by created date greater than value.
* `created_date.gte` / `created_on.gte`: Filters by created date greater than or equal to value.
* `created_date.lt` / `created_on.lt`: Filters by created date less than value.
* `created_date.lte` / `created_on.lte`: Filters by created date less than or equal to value.
* `ordering` (string): Sorts results by `created_at`, `shift_start_at`, `shift_end_at`, or `spots`, in ascending or descending order.
Shift Timing Filters
* `shift_date` (string, ISO-8601 date): Filters by the date portion of `shift_start_at`.
* `date` (string, ISO-8601 date): Alias for `shift_date`.
* `shift_date.gt` / `date.gt`: Filters by shift date greater than value.
* `shift_date.gte` / `date.gte`: Filters by shift date greater than or equal to value.
* `shift_date.lt` / `date.lt`: Filters by shift date less than value.
* `shift_date.lte` / `date.lte`: Filters by shift date less than or equal to value.
* `shift_start_at` (string, ISO-8601): Filters by exact shift start timestamp.
* `shift_start_at.gt`, `shift_start_at.gte`, `shift_start_at.lt`, `shift_start_at.lte`: Range filters for shift start timestamp.
* `shift_start_time` (string): Filters by the time portion of `shift_start_at`.
* `start_time` (string): Alias for `shift_start_time`.
* `shift_start_time.gt`, `shift_start_time.gte`, `shift_start_time.lt`, `shift_start_time.lte`: Range filters for shift start time.
* `shift_end_at` (string, ISO-8601): Filters by exact shift end timestamp.
* `shift_end_at.gt`, `shift_end_at.gte`, `shift_end_at.lt`, `shift_end_at.lte`: Range filters for shift end timestamp.
* `shift_end_time` (string): Filters by the time portion of `shift_end_at`.
* `end_time` (string): Alias for `shift_end_time`.
* `shift_end_time.gt`, `shift_end_time.gte`, `shift_end_time.lt`, `shift_end_time.lte`: Range filters for shift end time.
Capacity Filters
* `spots` (integer): Filters shifts by exact spot count.
* `spots.gt` (integer): Filters shifts by `spots > value`.
* `spots.gte` (integer): Filters shifts by `spots >= value`.
* `spots.lt` (integer): Filters shifts by `spots < value`.
* `spots.lte` (integer): Filters shifts by `spots <= value`.
Opportunity and Category Filters
* `opportunity.id` (uuid): Filters by related opportunity ID.
* `opportunity_id` (uuid): Alias for `opportunity.id`.
* `opportunity.title` (string): Filters by related opportunity title.
* `opportunity_title` (string): Alias for `opportunity.title`.
* `category.id` (uuid): Filters by related category ID.
* `category_id` (uuid): Alias for `category.id`.
* `category.title` (string): Filters by related category title.
* `category_title` (string): Alias for `category.title`.
Sample Requests
```http
# id
GET /api/shifts/search/?id=645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d
# title
GET /api/shifts/search/?title=morning
# opportunity role id
GET /api/shifts/search/?opportunity.id=2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1
# category id
GET /api/shifts/search/?category.id=d610ab31-e480-4ef1-9e35-94f94ebacde9
# shift date
GET /api/shifts/search/?shift_date=2026-02-12
# shift start time
GET /api/shifts/search/?start_time.gte=09:00
# shift end time
GET /api/shifts/search/?end_time.lte=17:00
# spots
GET /api/shifts/search/?spots.gte=2
# created_at
GET /api/shifts/search/?created_at=2026-02-05T07:40:29.324645Z
# ordering by shift start
GET /api/shifts/search/?ordering=shift_start_at
# ordering by spots descending
GET /api/shifts/search/?ordering=-spots
```
Authorization:
Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get(
"https://api.vomevolunteer.com/api/shifts/search/?title=morning&spots.gte=2",
headers=headers
)
```
Response Structure:
The response from this endpoint returns a paginated list of shifts that match the query parameters, including timing, spot counts, and the public share URL for each shift.
Example Response Object:
```json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"created_at": "2026-02-05T07:40:29.324645Z",
"shift_start_at": "2026-02-12T09:00:00Z",
"shift_end_at": "2026-02-12T13:00:00Z",
"spots": 10,
"spots_reserved": 4,
"spots_available": 6,
"opportunity": {
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-02T10:15:00Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
},
"shift_location": "123 Main Street",
"shift_title": "Morning Shift",
"shift_description": "Support setup and check-in.",
"share_shift_url": "https://api.vomevolunteer.com/api/share/shift/645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
"title": "Morning Shift",
"description": "Support setup and check-in."
}
]}
```
Example Response Structure
Summary Information
* `count`: Total number of matching shifts.
* `next`: URL for the next page of results, or `null`.
* `previous`: URL for the previous page of results, or `null`.
Shift Object
* `id`: Unique ID of the shift.
* `created_at`: Created timestamp of the shift.
* `shift_start_at`: Start timestamp of the shift.
* `shift_end_at`: End timestamp of the shift.
* `spots`: Total shift capacity.
* `spots_reserved`: Number of currently filled spots.
* `spots_available`: Number of remaining spots.
* `opportunity`: Related opportunity role object with nested category data.
* `shift_location`: Derived display location for the shift.
* `shift_title`: Stored shift title.
* `shift_description`: Stored shift description.
* `share_shift_url`: Public share URL for the shift.
* `title`: Alias of `shift_title`.
* `description`: Alias of `shift_description`.
Validation Rules
* Invalid date, datetime, time, or integer values return `400 Bad Request`.
* `ordering` only accepts `created_at`, `-created_at`, `shift_start_at`, `-shift_start_at`, `shift_end_at`, `-shift_end_at`, `spots`, or `-spots`.
* If no `ordering` is supplied, results default to `shift_start_at`, then `created_at`.
Example validation error:
```json
{
"detail": "Invalid date format for shift_start_at."
}
```
# Write Operations
# Assign users to shifts
The endpoint assigns one or more users to one or more shifts. If multiple user\_ids are provided, multiple users are assigned. If multiple shift\_ids are provided, each user is assigned to each shift.
If notify\_user is true, the API additionally triggers:
* shift approval notifications to users
#### Endpoint
`POST /api/shifts/bulk-assign/`
#### Payload sample
```json
{
"user_ids": [
"06d9d2da-e99d-4c9a-9f95-c9acd55e9ee1",
"de89a718-51f6-46e2-800f-56709879f179",
"5a8046f9-e698-49b7-b69f-a732ff13502b"
],
"shift_ids": [
"a167ac3f-952e-417d-85e6-6d4f74306950"
],
"notify_user": true
}
```
#### Response sample
```json
{
"assignment_count": 3,
"created_count": 3,
"existing_count": 0,
"enrollments": [
{
"id": "3b4e9461-8b34-4d5b-9c3d-48f6f85f0f01",
"user_id": "06d9d2da-e99d-4c9a-9f95-c9acd55e9ee1",
"shift_id": "a167ac3f-952e-417d-85e6-6d4f74306950",
"created": true
},
{
"id": "61a1f40d-1f5a-49f0-b3e7-34ac3f5dc6d7",
"user_id": "de89a718-51f6-46e2-800f-56709879f179",
"shift_id": "a167ac3f-952e-417d-85e6-6d4f74306950",
"created": true
},
{
"id": "a3cc6f4c-d0ed-44e5-9a94-c2e30d540f70",
"user_id": "5a8046f9-e698-49b7-b69f-a732ff13502b",
"shift_id": "a167ac3f-9528-417d-85e6-6d4f74306950",
"created": true
}
]
}
```
# Opportunities
This object represents an opportunity within your organization. An opportunity belongs to a category, and each category can have one or more opportunities attached to it (for example, a "Community Outreach" category may contain roles like "Weekend Mentor" and "Event Support").
If you're not familiar with Vome's system, the hierarchy works as follows: `Category > Opportunity`
Each opportunity stores the key details used to describe it, including its title, description, related category, and, when published, a public share URL.
You can use the Opportunities API to list all opportunities for your institution, retrieve a single opportunity by ID, or search opportunities using filters such as title, description, category, status, and created date.
**Endpoints**\
`GET /api/opportunities/`\
`GET /api/opportunities/{opportunity_role_id}/`\
`GET /api/opportunities/search/`
# The Opportunity Object
```json
{
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-05T07:40:29.324645Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
}
```
**Response Object**:
* `id` The unique UUID of the opportunity role.
* `category` The parent category or opportunity this role belongs to.
* `category.id` The unique UUID of the related category.
* `category.title` The name of the related category.
* `category.description` A short description of the related category.
* `title` The title or name of the opportunity.
* `description` A short description of the opportunity role and what it involves.
* `share_opportunity_url` A public-facing share link for the opportunity. This is only returned when the role is published. If the role is not published, this value may be `null`.
# List all opportunities
**Endpoint and Request Method:**\
`GET /api/opportunities/`\
This endpoint retrieves a paginated list of all opportunities for the authenticated institution.
**Example Request:**\
`GET https://api.vomevolunteer.com/api/opportunities/`
**Authorization:**\
Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get(
"https://api.vomevolunteer.com/api/opportunities/",
headers=headers
)
```
**Response Structure:**\
The response is a paginated object containing opportunity records. Each record represents a single opportunity along with its related category details and share URL.
**Response Object:**
```json
{
"count": 2,
"next": "https://api.vomevolunteer.com/api/opportunities/?page=2",
"previous": null,
"results": [
{
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-05T07:40:29.324645Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
},
{
"id": "ad7a99da-94c5-4e3f-8c6f-c2c8c7eb0a74",
"category": {
"id": "4a17144c-58c8-4103-8c0a-f2ac12079e7a",
"title": "Food Services",
"description": "Meal prep and food distribution roles."
},
"title": "Kitchen Support",
"description": "Assist staff with packaging and cleanup.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
}
]
}
```
# Retrieve a opportunity
**Endpoint**\
`GET /api/opportunities/{opportunity_id}/`
Replace `{opportunity_id}` with the actual ID of the opportunity role you wish to retrieve.
**Example Request**\
`GET /api/opportunities/2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1/`
**Authorization**\
Requests to this endpoint must include an `API-KEY` in the header for authentication:
```python
headers = {"API-KEY": "your_unique_api_key_here"}
response = requests.get(
"https://api.vomevolunteer.com/api/opportunities/2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1/",
headers=headers
)
```
**Response Object**\
The response object includes details about a single opportunity role, including its related category and share URL:
```json
{
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-05T07:40:29.324645Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
}
```
# Search opportunities
This endpoint allows for the efficient searching and filtering of opportunity role records based on specified query parameters such as title, description, category, status, and created date. It is designed to support operations that require accessing detailed opportunity role information quickly and effectively.
**Endpoint and Usage:**\
**Endpoint:** `GET /api/opportunities/search/`\
**Base URL:** `https://api.vomevolunteer.com`
**Query Parameters:**
**Core Filters**
* `id` (uuid): Filters opportunity roles by ID.
* `title` (string): Filters opportunity roles by title.
* `description` (string): Filters opportunity roles by description.
* `status` (string): Filters opportunity roles by status.
* `created_at` (string, ISO-8601): Filters opportunity roles by exact `created_at`.
* `created_at.gt` (string, ISO-8601): Filters by `created_at > value`.
* `created_at.gte` (string, ISO-8601): Filters by `created_at >= value`.
* `created_at.lte` (string, ISO-8601): Filters by `created_at <= value`.
* `created_at.lt` (string, ISO-8601): Filters by `created_at < value`.
* `ordering` (string): Sorts results by `created_at` or `-created_at`.
**Opportunity Statuses**
* `0`: Draft
* `1`: Published
* `2`: Unpublished
**Sample Requests**
```http
# id
GET /api/opportunities/search/?id=2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1
# title
GET /api/opportunities/search/?title=mentor
# description
GET /api/opportunities/search/?description=weekend
# status
GET /api/opportunities/search/?status=1
# created_at
GET /api/opportunities/search/?created_at=2024-09-06T02:57:15.008656Z
# created_at.gt
GET /api/opportunities/search/?created_at.gt=2024-09-06T02:57:15.008656Z
# created_at.gte
GET /api/opportunities/search/?created_at.gte=2024-09-06T02:57:15.008656Z
# created_at.lt
GET /api/opportunities/search/?created_at.lt=2024-09-06T02:57:15.008656Z
# created_at.lte
GET /api/opportunities/search/?created_at.lte=2024-09-06T02:57:15.008656Z
# ordering ascending
GET /api/opportunities/search/?ordering=created_at
# ordering descending
GET /api/opportunities/search/?ordering=-created_at
```
**Category Filters**\
Search by related category fields:
* `category.id` (uuid): Filters opportunity roles by the related category ID.
* `category_id` (uuid): Alias for `category.id`.
* `category.title` (string): Filters opportunity roles by the related category title.
* `category_title` (string): Alias for `category.title`.
**Sample Requests**
```http
# category id
GET /api/opportunities/search/?category.id=d610ab31-e480-4ef1-9e35-94f94ebacde9
# category_id alias
GET /api/opportunities/search/?category_id=d610ab31-e480-4ef1-9e35-94f94ebacde9
# category title
GET /api/opportunities/search/?category.title=Community Outreach
# category_title alias
GET /api/opportunities/search/?category_title=Community Outreach
```
**Authorization:**\
Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get(
"https://api.vomevolunteer.com/api/opportunities/search/?title=mentor&status=1",
headers=headers
)
```
**Response Structure:**\
The response from this endpoint returns a paginated list of opportunities that match the query parameters, including details about each role’s related category and public share URL.
**Example Response Object:**
```json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
"created_at": "2026-02-05T07:40:29.324645Z",
"category": {
"id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
"title": "Community Outreach",
"description": "Programs and roles related to outreach work."
},
"title": "Weekend Mentor",
"description": "Support volunteers during weekend sessions.",
"share_opportunity_url": "https://www.vomevolunteer.com/opportunity-board/test%20organization/weekend%20mentor/2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1"
}
]
}
```
**Example Response Structure**
**Summary Information**
* `count`: Total number of matching opportunity roles.
* `next`: URL for the next page of results, or `null`.
* `previous`: URL for the previous page of results, or `null`.
**Opportunity Role Object**
* `id`: Unique ID of the opportunity role.
* `category`: Related category information.
* `category.id`: Unique ID of the category.
* `category.title`: Title of the category.
* `category.description`: Description of the category.
* `title`: Title of the opportunity.
* `description`: Description of the opportunity.
* `share_opportunity_url`: Public share URL for the opportunity. This may be `null` if the role is not published.
# Write Operations
# Assign users to opportunities
The endpoint assigns one or more users to one or more opportunities. If multiple `user_ids` are provided, multiple users are assigned. If multiple `opportunity_ids` are provided, each user is assigned to each opportunity.
The endpoint only accepts published opportunities that belong to your institution. If an assignment already exists, it is returned with `"created": false`; otherwise a new enrollment is created. All assigned enrollments are set to approved status.
The API additionally triggers: opportunity assignment notifications to users\
chat user creation for the assigned enrollments
**Endpoint**\
`POST /api/opportunities/bulk-assign/`
**Payload sample**
```json
{
"user_ids": [
"06d9d2da-e99d-4c9a-9f95-c9acd55e9ee1",
"de89a718-51f6-46e2-800f-56709879f179",
"5a8046f9-e698-49b7-b69f-a732ff13502b"
],
"opportunity_ids": [
"a167ac3f-952e-417d-85e6-6d4f74306950"
]
}
```
**Response sample**
```json
{
"assignment_count": 3,
"created_count": 3,
"existing_count": 0,
"enrollments": [
{
"id": "3b4e9461-8b34-4d5b-9c3d-48f6f85f0f01",
"user_id": "06d9d2da-e99d-4c9a-9f95-c9acd55e9ee1",
"opportunity_id": "a167ac3f-952e-417d-85e6-6d4f74306950",
"created": true
},
{
"id": "61a1f40d-1f5a-49f0-b3e7-34ac3f5dc6d7",
"user_id": "de89a718-51f6-46e2-800f-56709879f179",
"opportunity_id": "a167ac3f-952e-417d-85e6-6d4f74306950",
"created": true
},
{
"id": "a3cc6f4c-d0ed-44e5-9a94-c2e30d540f70",
"user_id": "5a8046f9-e698-49b7-b69f-a732ff13502b",
"opportunity_id": "a167ac3f-952e-417d-85e6-6d4f74306950",
"created": true
}
]
}
```
# Sequences
This object represents a sequence within your organization. A sequence is an onboarding or workflow container made up of ordered steps, and each step can reference a specific requirement such as a form and waiver, interview, training, orientation, or onboarding document.
If you're not familiar with Vome's system, the hierarchy works as follows: Sequence > Step
Each sequence stores the key details used to describe it, including its title, description, status, visibility, and related step information. Returned sequence data includes the ordered step\_info array, where each step contains its step number, type, and step-specific details.
You can use the Sequences API to list all sequences for your institution, retrieve a single sequence by ID, or search sequences using filters such as title, description, status, display status, and created date.
Endpoints
GET /api/sequences/\
GET /api/sequences/{sequence\_id}/\
GET /api/sequences/search/
# The Sequence Object
```json
{
"id": "4f3c95f8-9422-4c19-a0d2-16ce344b5b5d",
"created_at": "2026-02-05T07:40:29.324645Z",
"updated_at": "2026-02-07T11:10:00Z",
"title": "Welcome Flow",
"description": "Getting started",
"folder": {
"id": "4ae2f969-a6ed-4e52-b720-c5db1d85fdb2",
"name": "Basketball"
},
"status": "Published",
"display_status": "Public",
"number_users_active": 3,
"number_users_paused": 0,
"number_users_inactive": 0,
"number_users_finished": 1,
"number_active_steps": 2,
"step_info": [
{
"id": "a437d244-c22a-4be1-8a72-6dd3f0e8af32",
"step": 1,
"type": 1,
"type_display": "Interview",
"step_details": [
{
"id": "74ac1ec8-e26c-4984-b868-79c55e245c66",
"title": "Interview",
"description": "Interview step"
}
]
}
]
}
```
This object represents a sequence within your organization. A sequence groups onboarding or workflow steps together and tracks how many users are active, paused, inactive, or finished in that sequence.
Response Object:
* `id`: The unique UUID of the sequence.
* `created_at`: The timestamp when the sequence was created.
* `updated_at`: The timestamp when the sequence was last updated.
* `title`: The title or name of the sequence.
* `description`: A short description of the sequence.
* `folder`: The folder the sequence belongs to, if one is set.
* `folder.id`: The unique UUID of the sequence folder.
* `folder.name`: The name of the sequence folder.
* `status`: The display value of the sequence status in the response. Possible values are `Draft`, `Published`, and `Unpublished`.
* `display_status`: The display value of the sequence visibility in the response. Possible values are `Private` and `Public`.
* `number_users_active`: Count of volunteers currently active in the sequence.
* `number_users_paused`: Count of volunteers currently paused in the sequence.
* `number_users_inactive`: Count of volunteers currently inactive in the sequence.
* `number_users_finished`: Count of volunteers who have finished the sequence.
* `number_active_steps`: Count of active steps attached to the sequence.
* `step_info`: An ordered array of sequence step objects.
* `step_info.id`: The unique UUID of the step.
* `step_info.step`: The step number within the sequence.
* `step_info.type`: The numeric step type identifier.
* `step_info.type_display`: The human-readable step type.
* `step_info.step_details`: Step-specific details. The shape varies by step type.
Detailed Step Info Breakdown
Step Info Object
* `id` (string): Unique identifier of the sequence step row.
* `step` (integer): Sequential order number of the step.
* `type` (integer): Numeric type of the step.
* `type_display` (string): Human-readable name of the step type.
* `step_details` (array): Detailed metadata for the step. The structure depends on `type`.
Step Types
* `0`: Forms And Waiver
* `1`: Interview
* `2`: Training
* `3`: Orientation
* `4`: Onboarding Other
* `5`: Electronic Signature
* `6`: Form Step
* `7`: Video
* `8`: Checklist
* `9`: Sterling Background Check
* `10`: SCORM File
Step Details by Type
* For `0`, `1`, `2`, `3`, and `4`, `step_details` returns an array of basic content objects with:
* `id` (string): Unique identifier of the underlying step content item.
* `title` (string): Title of the step content item.
* `description` (string): Description of the step content item.
* For `5` (Electronic Signature), `step_details` returns an array of electronic signature objects with:
* `document_title` (string): Title of the signature document.
* `description` (string): Description of the signature document.
* `document_file` (string | null): File attached to the electronic signature step.
* `is_active` (boolean): Whether the step is active.
* `signature_areas` (array): Signature field definitions on the document.
* `user_electronic_signatures` (array): User-specific signature records. In `/api/sequences/`, this is typically empty because the endpoint is not user-scoped.
* For `9` (Sterling Background Check), `step_details` returns an array of background check objects with:
* `title` (string): Step title.
* `description` (string): Step description.
* `package_id` (string): Sterling package identifier.
* `is_active` (boolean): Whether the step is active.
* `user_sterling_step` (array): User-specific Sterling records. In `/api/sequences/`, this is typically empty because the endpoint is not user-scoped.
* For `10` (SCORM File), `step_details` returns an array of SCORM course objects with:
* `title` (string): Step title.
* `description` (string): Step description.
* `scorm_file` (string | null): SCORM file reference.
* `is_active` (boolean): Whether the step is active.
* `cloud_course_id` (string | null): Cloud course identifier.
* `user_scorm_step` (array): User-specific SCORM step records. In `/api/sequences/`, this is typically empty because the endpoint is not user-scoped.
* If a step type has no expanded serializer in this endpoint, or the related step record is missing, `step_details` is returned as an empty array.
# List all sequences
Endpoint and Request Method:
`GET /api/sequences/`
This endpoint retrieves a paginated list of all sequences for the authenticated institution.
Example Request:
`GET https://api.vomevolunteer.com/api/sequences/`
Authorization:
Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get(
"https://api.vomevolunteer.com/api/sequences/",
headers=headers
)
```
Supported query parameters:
* `page`: Page number.
* `page_size`: Number of results per page, up to `100`.
* `status`: Filters by sequence status (`0` = Draft, `1` = Published, `2` = Unpublished).
* `display_status`: Filters by sequence visibility (`0` = Private, `1` = Public).
Response Structure:
The response is a paginated object containing sequence records. Each record represents a single sequence along with folder details, volunteer counts, and step metadata.
Response Object:
```json
{
"count": 2,
"next": "https://api.vomevolunteer.com/api/sequences/?page=2",
"previous": null,
"results": [
{
"id": "4f3c95f8-9422-4c19-a0d2-16ce344b5b5d",
"created_at": "2026-02-05T07:40:29.324645Z",
"updated_at": "2026-02-07T11:10:00Z",
"title": "Welcome Flow",
"description": "Getting started",
"folder": {
"id": "4ae2f969-a6ed-4e52-b720-c5db1d85fdb2",
"name": "Basketball"
},
"status": "Published",
"display_status": "Public",
"number_users_active": 3,
"number_users_paused": 0,
"number_users_inactive": 0,
"number_users_finished": 1,
"number_active_steps": 2,
"step_info": []
},
{
"id": "e3ef4ae1-1ba9-4df8-b5c9-8588ee53b272",
"created_at": "2026-02-03T09:12:00Z",
"updated_at": "2026-02-06T12:20:00Z",
"title": "Safety Training Flow",
"description": "Compliance onboarding",
"folder": null,
"status": "Draft",
"display_status": "Private",
"number_users_active": 0,
"number_users_paused": 0,
"number_users_inactive": 0,
"number_users_finished": 0,
"number_active_steps": 2,
"step_info": [
{
"id": "cb776f05-6404-44c6-8ed4-0aafdaca9a87",
"step": 1,
"type": 1,
"type_display": "Interview",
"step_details": [
{
"id": "104faf42-9dca-450e-9b3b-7a4cd38af999",
"title": "In-person",
"description": "
"
}
]
}
]
}
}
]
}
```
# Retrieve a Sequence
Endpoint
`GET /api/sequences/{sequence_id}/`
Replace `{sequence_id}` with the actual ID of the sequence you wish to retrieve.
Example Request
`GET /api/sequences/4f3c95f8-9422-4c19-a0d2-16ce344b5b5d/`
Authorization
Requests to this endpoint must include an `API-KEY` in the header for authentication:
```python
headers = {"API-KEY": "your_unique_api_key_here"}
response = requests.get(
"https://api.vomevolunteer.com/api/sequences/4f3c95f8-9422-4c19-a0d2-16ce344b5b5d/",
headers=headers
)
```
Response Object
The response object includes details about a single sequence, including folder metadata, user counts, and step information:
```json
{
"id": "4f3c95f8-9422-4c19-a0d2-16ce344b5b5d",
"created_at": "2026-02-05T07:40:29.324645Z",
"updated_at": "2026-02-07T11:10:00Z",
"title": "Welcome Flow",
"description": "Getting started",
"folder": {
"id": "4ae2f969-a6ed-4e52-b720-c5db1d85fdb2",
"name": "Basketball"
},
"status": "Published",
"display_status": "Public",
"number_users_active": 3,
"number_users_paused": 0,
"number_users_inactive": 0,
"number_users_finished": 1,
"number_active_steps": 2,
"step_info": [
{
"id": "a437d244-c22a-4be1-8a72-6dd3f0e8af32",
"step": 1,
"type": 1,
"type_display": "Interview",
"step_details": [
{
"id": "74ac1ec8-e26c-4984-b868-79c55e245c66",
"title": "Interview",
"description": "Interview step"
}
]
}
]
}
```
Common errors:
* `404 Not Found`: The sequence does not exist, or it does not belong to the authenticated institution.
Example:
```json
{
"detail": "Not found."
}
```
# Search Sequences
This endpoint allows for the efficient searching and filtering of sequence records based on specified query parameters such as title, description, status, visibility, and created date. It is designed to support operations that require accessing detailed sequence information quickly and effectively.
Endpoint and Usage:
Endpoint: `GET /api/sequences/search/`
Base URL: `https://api.vomevolunteer.com`
Query Parameters:
Core Filters
* `id` (uuid): Filters sequences by ID.
* `title` (string): Filters sequences by title.
* `description` (string): Filters sequences by description.
* `status` (string): Filters sequences by status (`0` = Draft, `1` = Published, `2` = Unpublished).
* `display_status` (string): Filters sequences by visibility (`0` = Private, `1` = Public).
* `created_at` (string, ISO-8601): Filters sequences by exact `created_at`.
* `created_at.gt` (string, ISO-8601): Filters by `created_at > value`.
* `created_at.gte` (string, ISO-8601): Filters by `created_at >= value`.
* `created_at.lte` (string, ISO-8601): Filters by `created_at <= value`.
* `created_at.lt` (string, ISO-8601): Filters by `created_at < value`.
* `ordering` (string): Sorts results by `created_at` or `-created_at`.
Sequence Statuses
* `0`: Draft
* `1`: Published
* `2`: Unpublished
Display Statuses
* `0`: Private
* `1`: Public
Sample Requests
```http
# id
GET /api/sequences/search/?id=4f3c95f8-9422-4c19-a0d2-16ce344b5b5d
# title
GET /api/sequences/search/?title=welcome
# description
GET /api/sequences/search/?description=onboarding
# status
GET /api/sequences/search/?status=1
# display_status
GET /api/sequences/search/?display_status=1
# created_at
GET /api/sequences/search/?created_at=2026-02-05T07:40:29.324645Z
# created_at.gt
GET /api/sequences/search/?created_at.gt=2026-02-05T07:40:29.324645Z
# created_at.gte
GET /api/sequences/search/?created_at.gte=2026-02-05T07:40:29.324645Z
# created_at.lt
GET /api/sequences/search/?created_at.lt=2026-02-05T07:40:29.324645Z
# created_at.lte
GET /api/sequences/search/?created_at.lte=2026-02-05T07:40:29.324645Z
# ordering ascending
GET /api/sequences/search/?ordering=created_at
# ordering descending
GET /api/sequences/search/?ordering=-created_at
```
Authorization:
Requests to this endpoint require an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get(
"https://api.vomevolunteer.com/api/sequences/search/?title=welcome&status=1",
headers=headers
)
```
Response Structure:
The response from this endpoint returns a paginated list of sequences that match the query parameters, including folder metadata, counts, and step information for each sequence.
Example Response Object:
```json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "4f3c95f8-9422-4c19-a0d2-16ce344b5b5d",
"created_at": "2026-02-05T07:40:29.324645Z",
"updated_at": "2026-02-07T11:10:00Z",
"title": "Welcome Flow",
"description": "Getting started",
"folder": {
"id": "4ae2f969-a6ed-4e52-b720-c5db1d85fdb2",
"name": "Basketball"
},
"status": "Published",
"display_status": "Public",
"number_users_active": 3,
"number_users_paused": 0,
"number_users_inactive": 0,
"number_users_finished": 1,
"number_active_steps": 2,
"step_info": []
}
]
}
```
Example Response Structure
Summary Information
* `count`: Total number of matching sequences.
* `next`: URL for the next page of results, or `null`.
* `previous`: URL for the previous page of results, or `null`.
Sequence Object
* `id`: Unique ID of the sequence.
* `created_at`: Created timestamp of the sequence.
* `updated_at`: Last updated timestamp of the sequence.
* `title`: Sequence title.
* `description`: Sequence description.
* `folder`: Related folder object, or `null`.
* `status`: Human-readable sequence status in the response.
* `display_status`: Human-readable visibility status in the response.
* `number_users_active`: Count of active users.
* `number_users_paused`: Count of paused users.
* `number_users_inactive`: Count of inactive users.
* `number_users_finished`: Count of finished users.
* `number_active_steps`: Count of active steps.
* `step_info`: Ordered step metadata array.
Validation Rules
* Invalid timestamps return `400 Bad Request`.
* `ordering` only accepts `created_at` or `-created_at`.
* If no `ordering` is supplied, results default to `-created_at`.
Example validation error:
```json
{
"detail": "Invalid date format for created_at."
}
```
# Write Operations
# Assign users to sequences
The endpoint assigns one or more users to one or more sequences. If multiple `user_ids` are provided, multiple users are assigned. If multiple `sequence_ids` are provided, each user is assigned to each sequence.
The endpoint only accepts published sequences that belong to your institution. If an assignment already exists, it is returned as part of the response and counted under `existing_count`. If a new assignment is created, it is counted under `created_count`.
The API additionally triggers: sequence volunteer notifications to users
**Endpoint**\
`POST /api/sequences/bulk-assign/`
**Payload sample**
```json
{
"user_ids": [
"06d9d2da-e99d-4c9a-9f95-c9acd55e9ee1",
"de89a718-51f6-46e2-800f-56709879f179",
"5a8046f9-e698-49b7-b69f-a732ff13502b"
],
"sequence_ids": [
"a167ac3f-952e-417d-85e6-6d4f74306950"
]
}
```
**Response sample**
```json
{
"assignment_count": 3,
"created_count": 3,
"existing_count": 0,
"enrollments": [
{
"id": "3b4e9461-8b34-4d5b-9c3d-48f6f85f0f01",
"user_id": "06d9d2da-e99d-4c9a-9f95-c9acd55e9ee1",
"sequence_id": "a167ac3f-952e-417d-85e6-6d4f74306950"
},
{
"id": "61a1f40d-1f5a-49f0-b3e7-34ac3f5dc6d7",
"user_id": "de89a718-51f6-46e2-800f-56709879f179",
"sequence_id": "a167ac3f-952e-417d-85e6-6d4f74306950"
},
{
"id": "a3cc6f4c-d0ed-44e5-9a94-c2e30d540f70",
"user_id": "5a8046f9-e698-49b7-b69f-a732ff13502b",
"sequence_id": "a167ac3f-952e-417d-85e6-6d4f74306950"
}
]
}
```
# Sites
This guide covers the endpoints for working with organization sites and user-to-site memberships through the Vome Integrations API.
Endpoints
GET /api/sites/\
GET /api/sites/{site\_id}/\
POST /api/sites/bulk-create/\
POST /api/sites/assign/\
POST /api/sites/unassign/
# The Site Object
```json
{
"id": "8f2c1e5a-....",
"name": "Downtown Clinic",
"description": "",
"address": "12 King St",
"general_email": "downtown@example.org",
"general_phone": "+15551234567",
"website": "https://downtown.example.org"
}
```
This object represents a site within your organization. A site is typically represented as a location within a multi-site organization, but can be defined differently across organizations.
Response Object:
* `id`: The unique UUID of the site.
* `name`: The name of the site.
* `description`: A short description of the site.
* `address`: The address of the site.
* `general_email`: The general email of the site.
* `general_phone`: The general phone number of the site.
* `website`: The website of the site.
# List all sites
## List all sites
This endpoint is used to retrieve a list of all sites in your organization.
**Endpoint Description:**
* **Endpoint**: `GET /api/sites/`
* **Base URL**: `https://api.vomevolunteer.com`
**Query Parameters:**
* **name** (`string`): Case-insensitive "contains" filter on the site name.
* **page** (`integer`): Page number (default 1).
* **page\_size** (`integer`): Items per page (default 25, max 200).
* **limit** (`integer`): Alias for `page_size`.
**Example Request:**
```http
GET https://api.vomevolunteer.com/api/sites/
```
**Authorization:**
Requests to this endpoint must include an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/sites/", headers=headers)
```
**Response Structure:**
```json
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "8f2c1e5a-....",
"name": "Downtown Clinic",
"description": "",
"address": "12 King St",
"general_email": "downtown@example.org",
"general_phone": "+15551234567",
"website": "https://downtown.example.org"
}
]
}
```
# Retrieve a Site
This endpoint retrieves detailed information about a specific site by its ID.
**Endpoint Description:**
* **Endpoint**: `GET /api/sites/{site_id}/`
* **Base URL**: `https://api.vomevolunteer.com`
**Path Parameter:**
* **site\_id** (`string`): The unique identifier for the site to be retrieved.
**Example Request:**
```http
GET https://api.vomevolunteer.com/api/sites/8f2c1e5a-..../
```
**Authorization:**
Requests to this endpoint must include an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.get("https://api.vomevolunteer.com/api/sites/8f2c1e5a-..../", headers=headers)
```
**Response Structure:**
Returns the same fields as a list item. Returns a `404` if the site does not exist in your organization.
```json
{
"id": "8f2c1e5a-....",
"name": "Downtown Clinic",
"description": "",
"address": "12 King St",
"general_email": "downtown@example.org",
"general_phone": "+15551234567",
"website": "https://downtown.example.org"
}
```
# Write Operations
# Create sites
This endpoint is used to create sites in your organization. It accepts either a single object or a list of objects. Sites will only be created if they do not already exist.
Please note, you must add a **name** when creating a site. Names that already exist for your organization are skipped (not created), and matching is case-insensitive.
**Endpoint Description:**
* **Endpoint**: `POST /api/sites/bulk-create/`
* **Base URL**: `https://api.vomevolunteer.com`
**API specification:**
* **name** (`string`, required): Site name.
* **description** (`string` | `null`): Defaults to empty.
* **address** (`string` | `null`): Defaults to empty.
* **general\_email** (`string` | `null`): Valid email or null.
* **general\_phone** (`string` | `null`): Up to 17 characters, or null.
* **website** (`string` | `null`): Up to 300 characters, or null.
**Authorization:**
Requests to this endpoint must include an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.post("https://api.vomevolunteer.com/api/sites/bulk-create/", headers=headers)
```
**Example Request Payload:**
```json
[
{ "name": "Downtown Clinic" },
{
"name": "North Branch",
"address": "12 King St",
"website": "https://north.example.org"
}
]
```
**Response Structure:**
```json
{
"created": [
{
"id": "8f2c1e5a-....",
"name": "Downtown Clinic",
"description": "",
"address": "",
"general_email": null,
"general_phone": null,
"website": null
}
],
"skipped": [
{ "name": "North Branch", "reason": "already exists" }
]
}
```
*Note: Names that already exist for your organization are skipped, as are duplicate names within the same payload. This makes imports safe to retry.*
# Assign users to sites
This endpoint assigns one or more users to one or more sites. Every listed site is applied to every listed user (a cartesian assignment). It supports single or bulk input using the same body shape.
**Endpoint Description:**
* **Endpoint**: `POST /api/sites/assign/`
* **Base URL**: `https://api.vomevolunteer.com`
**API specification:**
* **user\_ids** (`array`): List of Vome IDs.
* **site\_ids** (`array`): List of site ids.
* **user\_id** (`string`): Single Vome ID; normalized into `user_ids`.
* **site\_id** (`string`): Single site id; normalized into `site_ids`.
**Authorization:**
Requests to this endpoint must include an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.post("https://api.vomevolunteer.com/api/sites/assign/", headers=headers)
```
**Example Request Payload:**
```json
{
"user_ids": ["", ""],
"site_ids": ["", ""]
}
```
**Response Structure:**
```json
{
"assigned": [
{ "user_id": "", "assigned_site_ids": ["", ""] },
{ "user_id": "", "assigned_site_ids": ["", ""] }
],
"skipped_user_ids": []
}
```
*Note: Assigning a site the user already has is a no-op; existing memberships are not removed. Any `user_id` that is not a profile in your organization is returned in `skipped_user_ids`; the rest still process. Unknown sites fail the whole call with a `400`: `{ "site_ids": "Unknown site(s): " }`.*
# Remove users from sites
This endpoint removes one or more users from one or more sites. It uses an identical body to the assign endpoint, and supports single or bulk input.
**Endpoint Description:**
* **Endpoint**: `POST /api/sites/unassign/`
* **Base URL**: `https://api.vomevolunteer.com`
**API specification:**
* **user\_ids** (`array`): List of Vome IDs.
* **site\_ids** (`array`): List of site ids.
* **user\_id** (`string`): Single Vome ID; normalized into `user_ids`.
* **site\_id** (`string`): Single site id; normalized into `site_ids`.
**Authorization:**
Requests to this endpoint must include an `API-KEY` in the header for authentication.
```python
headers = {
"API-KEY": "your_unique_api_key_here"
}
response = requests.post("https://api.vomevolunteer.com/api/sites/unassign/", headers=headers)
```
**Example Request Payload:**
```json
{
"user_ids": ["", ""],
"site_ids": ["", ""]
}
```
**Response Structure:**
```json
{
"removed": [
{ "user_id": "", "removed": 2 }
],
"skipped_user_ids": []
}
```
*Note: `removed` is the count of membership rows deleted for that user. As with assign, unknown users are returned in `skipped_user_ids` and are not fatal; only unknown sites produce a `400`.*
# Zapier
Integrating Vome with Zapier offers thousands of ways to integrate Vome into other applications to automate workflows using apps that you're already using!
To get started with using Vome on Zapier, follow these steps:
**Step 1: Generate a New API Key**
1\. Login to Vome and navigate to your Developer console.
* Once logged in, you can visit the **Integrations & Apps** page > Click on **API & webhooks**. *Or, you can login and visit this link directly:* [*Vome Developer Console.* ](https://www.vomevolunteer.com/developers)
2\. Create a new API key by selecting “**Generate API Key**”.
3\. Copy the API key and keep it somewhere safe – you’ll need it for authenticating with Zapier!
**Step 2: Authenticate Vome in Zapier**
1\. Go to [Zapier](https://zapier.com/) and log in to your account.
2\. When setting up a Vome-triggered Zap for the first time, you’ll be prompted to authenticate.
3\. In the authentication field, paste the API key you generated from the Vome Developer Console.
4\. Click *Authenticate* or *Continue*. You should see a confirmation if the authentication is successful.
**Step 3: Set Up Vome Triggers**
1\. Once authenticated, select the Vome app in Zapier.
2\. Choose from the available triggers, such as “New Profile” or “New Reservation.”
3\. Follow the Zapier steps to connect these triggers to your preferred actions in other apps.
**Troubleshooting**
If you experience any issues with authentication:
• Ensure the API key was copied correctly and is active.
• Double-check your internet connection.
• Contact us by visiting [support.vomevolunteer.com](https://support.vomevolunteer.com) if the issue persists.
# Microsoft Power Automate
Integrating Vome with Microsoft power automate offers thousands of ways to integrate Vome into other applications to automate workflows using apps that you're already using!
**1. Generate a New API Key:**
* Login to Vome and navigate to your Developer console.
* You can either visit the **Integrations & Apps** page > Click on **API & webhooks**. Or, you can login and visit this link: [Vome Developer Console. ](https://www.vomevolunteer.com/developers)
* Create a new API key by selecting “**Generate API Key**”.
* Copy the generated API key for use in Power Automate.
**2. Authenticate Vome in Power Automate:**
* Log in to your [Microsoft Power Automate](https://flow.microsoft.com) account.
* When setting up a Vome-triggered flow for the first time, you’ll be prompted to authenticate.
* Paste the API key from the Vome Developer Console into the authentication field.
* Click “Authenticate” or “Continue” to confirm successful authentication.
**3. Set Up Vome Triggers:**
* After authentication, select the **Vome connector** in Power Automate.
* Choose from available triggers, such as “New Profile” or “New Reservation.”
* Follow Power Automate’s instructions to connect these triggers to your desired actions in other apps.
**Troubleshooting Tips:**
• Ensure the API key is correctly copied and active.
• Verify your internet connection.
• Contact us by visiting [support.vomevolunteer.com](https://support.vomevolunteer.com) if the issue persists.
# Salesforce
{% hint style="info" %}
**Need help?** If you run into any issues installing the Salesforce app, or if you'd like to request any additional functionality, contact us at [support.vomevolunteer.com](https://support.vomevolunteer.com/).
{% endhint %}
***
## Salesforce Integration Setup
The Vome Integration Dashboard connects Salesforce with Vome for contact synchronization, automation, and data exchange. This guide walks through the full setup from installation through validation.
**What you'll do in this guide**
1. **Install** the Vome managed package and enable Apex metadata deployment
2. **Configure** authentication, OAuth, field mapping, and webhooks
3. **Validate** the integration by activating flows and checking sync rules
***
### 1. Pre-Installation Checklist
Before starting, confirm you have all of the following.
#### Credentials & access
* Salesforce System Administrator access to the target org
* **API Key** - provided by Vome, which is available for admins using Vome's Ultimate plan.
* **Client ID** and **Client Secret** - retrieved from your Salesforce org's **App Manager** *after* the package is installed (see Section 5B)
#### Salesforce areas you'll need
* Setup access
* Sites, Flows, Custom Metadata Types, Permission Sets
* Confirmed environment: **Sandbox (Test)** or **Production (Live)**
***
### 2. Install the Managed Package
1. Open the Vome managed package installation link:
2. **Sandbox?** Replace `login` with `test` in the URL before opening.
3. Authenticate with your Salesforce credentials.
4. Choose **Install for All Users**, then click **Install**.
5. When prompted, approve third-party access for `api.vomevolunteer.com`.
6. Wait for installation to complete.\
\
**Sandbox vs. Production URLs**
The installation link defaults to Production (`login.salesforce.com`). For sandboxes, swap `login` → `test`:
```
https://test.salesforce.com/packaging/installPackage.apexp?p0=04tgK000000ANL7
```
***
### 3. Enable Apex Metadata Deployment
This setting lets the package dynamically write and update configuration records at runtime. Without it, the integration cannot apply dynamic configuration changes automatically.
1. Go to **Setup**.
2. In Quick Find, search for **Apex Settings**.
3. Enable **Deploy Metadata from Non-Certified Package Versions via Apex**.
4. Click **Save**.
***
### 4. Configure the Webhook Site
A Salesforce Site is what lets Vome call back into your org.
1. Go to **Setup → Sites** and click **New Site**.
2. Enter a Site Name (e.g., `Vome Integration`) and set **Active = TRUE**. Fill in any other required info and click **Save.**
3. You will now see your newly created Site. Click on the **name of the Site**, which will bring you to the **Site Details page**.
4. Open **Public Access Settings** and grant access to the Apex class `VomeWebhookEndpoint`.
{% hint style="info" %}
Note the Site's custom URL domain (e.g., `yourorg--dev.sandbox.my.salesforce-sites.com`). You'll need it for the Vome webhook endpoint in Section 10.
{% endhint %}
***
### 5. Integration Authentication
Authentication has three parts: Vome Settings, OAuth Configuration, and Field Mapping.
#### A. Vome Settings (Custom Metadata)
1. Go to **Setup → Custom Metadata Types**
2. You will see a label called **Vome Setting →** Click **Manage Records → New**
3. Enter the following values:
| Field | Value |
| -------- | ------------------------------- |
| Label | `Vome Setting (Production)` |
| Name | `Production` |
| Base URL | `https://api.vomevolunteer.com` |
| API Key | *Found on Vome (see below)* |
{% hint style="info" %}
To create an API key on Vome, please see [Authentication](/getting-started/publish-your-docs) for detailed steps.
{% endhint %}
#### B. OAuth Configuration
1. Go to **Setup → Custom Metadata Types**
2. You will see a label called **Vome OAuth Config →** Click **Manage Records → New**
3. Name the record `Default`.
4. Enter the following values:
| Field | Value |
| ------------- | --------------------------------------------------- |
| Client ID | *From Salesforce App Manager* |
| Client Secret | *From Salesforce App Manager* |
| Redirect URI | `https://api.vomevolunteer.com/sfdc/oauth/callback` |
| Vome API Key | *From Vome (see above)* |
#### C. Field Mapping Configuration
Field mapping controls how data flows between Salesforce and Vome. If either bundle is inactive, records may not sync correctly.
1. Go to **Setup → Custom Metadata Types**
2. You will see a label called **Fieldmap Bundle →** Click **Manage Records**.
3. Confirm both of these are **Active**:
* `Contact Default Bundle`
* `Account Default Bundle`
***
### 6. Activate the Sync Flow
1. Go to **Setup → Flows**.
2. Locate the flow named **Sync Contact To Vome Trigger**.
3. Open the flow (using the arrow on the right-hand side **→** Click **View Details And Versions**
4. Click **Activate**.
This enables automatic syncing of contacts between Salesforce and Vome.
***
### 7. Tour the Integration Dashboard
The Vome Integration Dashboard has three tabs:
Tab
Purpose
Settings
Vome integration credentials
Field Mapping
Map Vome fields to Salesforce fields; add new mappings with + Add New Mapping
Integration Rules
Define when sync happens (on create, on update, or on a schedule)
***
### 8. Verify Integration Rules
On the **Integration Rules** tab, confirm these rules exist and are active:
| Rule | Trigger |
| -------------- | --------------- |
| Upsert Contact | Contact Created |
| Update Contact | Contact Updated |
| Daily Sync | Scheduled |
***
### 9. Assign Permission Sets
1. Go to **Setup → Permission Sets**.
2. Find and Click **Vome Integration User**.
3. Click **Manage Assignments → Add Assignments**.
4. Select the users who need access and click **Assign**.
***
### 10. Configure the Vome Webhook
Finally, register your Salesforce Site URL with Vome so events can flow back.
1. Log in to Vome > Integrations & apps > API & webhooks > webhooks
2. Click **+ Add Endpoint**.
3. Enter the webhook URL, using the Site domain from Section 4:
```
https://[Your-Site-Domain]/services/apexrest/Vome/vome/rules/webhook
```
4. Select the events you wish to enable for this webhook
{% hint style="info" %}
For example, if you want to update Salesforce when new profiles are added into Vome, you can enable that trigger event. You can include as many events as you expect to integrate with Salesforce
{% endhint %}
1. Set **Status = Active** and click **Save**.
***
### Troubleshooting
> **Integration not applying configuration changes?**
>
> Check that "Deploy Metadata from Non-Certified Package Versions via Apex" is enabled (Section 3).
> **Contacts aren't syncing?**
>
> Verify the **Sync Contact To Vome Trigger** flow is activated (Section 6) and that both Field Map Bundles are active (Section 5C).
> **Webhook events not arriving?**
>
> Confirm the Site is Active, `VomeWebhookEndpoint` has Public Access, and the endpoint registered in Vome matches your Site's custom domain exactly.
If you need help or have additional questions, reach out to us at contact us at [support.vomevolunteer.com](https://support.vomevolunteer.com/).