IMPORTANT: The target audience for this topic is Technical and IT staff in your organization.
API Functionality
Volunteer Impact API enables you to request profile data from Volunteer Impact to be used in an external program or application.
Sample API Client
A sample API Client (implemented in C#) is available at: https://github.com/BetterImpact/ApiClient.
Authentication
Our API uses HTTP basic authentication over HTTPS.
API Endpoints: Listing Users
Organization: https://api.betterimpact.com/v1/organization/users/
Parameters:
None.
Query parameters:
Parameter | Description | Valid Values/Defaults |
page_size | The number of results per page. | 1 to 250 |
page_number | The page number to retrieve. | 0 to * |
include_ | Whether or not to include custom fields in the results. | “true” or “false” |
include_ | Whether or not to include qualifications in the results. | “true” or “false” |
include_ | Whether or not to include membership information in the results. | “true” or “false” |
include_ | Whether or not to include Verified Volunteers background check information in the results. | “true” or “false” |
organization_ids | ENTERPRISE ENDPOINT ONLY. Comma separated list of organization IDs to return results for. This will return all users who belong to any of the organizations passed. | Comma separated list of valid organization IDs (integers) |
modules | A comma separated list of the module members you would like to return. | You may use the full, or short form for the module names: |
admin_status | A comma separated list of the admin statuses you would like to restrict the results to. | active |
client_status | A comma separated list of the client statuses you would like to restrict the results to. | applicant |
donor_status | A comma separated list of the donor statuses you would like to restrict the results to. | prospect |
member_status | A comma separated list of the member statuses you would like to restrict the results to. | applicant |
volunteer_status | A comma separated list of the volunteer statuses you would like to restrict to. | applicant |
updated_since | This parameter will restrict the results to profiles that have changed since the date specified. | DateTimes are required to be in ISO 8601 format (using the format string: “yyyy’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffK”). Please see this documentation for more information: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier. |
Response parameters:
Property | Type | Description |
Header | Object. See below for properties. | Header information related to paging and result set. |
Users | Array of user objects. See single User section for property descriptions. | A list of the users that match the query parameters. |
Header Properties:
Property | Type | Description |
first_item_on_page | integer | The 1 based index of the first item in the returned page of the users collection. |
has_next_page | boolean | True if there is more pages to be returned. |
has_previous_page | boolean | True if there is pages before the returned users collection. |
is_first_page | boolean | True if returned collection is page 1. |
is_last_page | boolean | True if returned collection is the last page. |
last_item_on_page | integer | The 1 based index of the last item in the returned page of the users collection. |
page_count | integer | The number of pages in the users collection. |
page_number | integer | The number of the page returned. |
page_size | integer | The size of the page returned. |
total_items_count | integer | The total number of users that match the query parameters across all pages. |
API Endpoints: Single User
Organization: https://api.betterimpact.com/v1/organization/users/{user_id}
Parameters:
Parameter | Description |
{user_id} | The user id of the user you wish to retrieve. |
Query parameters:
None.
Response:
A single user document, containing its own fields, as well as membership documents, custom fields documents, and qualifications documents.
Qualifications will only be included if your API user credentials have access to the Volunteer module.
Custom Fields will only be included if your API user credentials have access to at least one module that is specified on the custom field (the intersection between your modules and the ones on the custom field.).
User Properties:
Property | Type | Description / Notes |
user_id | integer | Unique id of user |
first_name | string | First name |
last_name | string | Last name |
legal_first_name | string | Legal first name |
middle_name | string | Middle name |
title | string | Title (salutation) |
suffix | string | Suffix |
pronouns | string | Pronouns |
address_line_1 | string | Line 1 of Address |
address_line_2 | string | Line 2 of Address |
city | string | City |
zip_code | string | Zip Code / Postal Code / Post Code |
state | string | State / Province / County |
country | string | Country |
email_address | string | Email address |
secondary_email_address | string | Secondary email address |
mobile_email_address | string | Mobile email address |
home_phone | string | Home phone number |
work_phone | string | Work phone number |
work_phone_ext | string | Work phone number extension |
cell_phone | string | Cell / Mobile phone number |
phone_preference | string | Phone preference |
twitter_username | string | Twitter username |
linkedIn_profile_url | string | LinkedIn profile URL |
Instagram_username | string | Instagram username |
username | string | Username |
birthday | string | Birthday in ISO 8601 UTC format (may be null) |
date_created | string | Date profile was created in ISO 8601 UTC format |
date_updated | string | Date profile was last updated in ISO 8601 UTC format |
region | string | Localized Name of the region |
region_code | string | Language code for region |
is_group | boolean | Does this profile represent a group |
group_name | string | Group name |
photo_url_scaled | string | URL of a scaled down version of the user’s photo |
photo_url_original | string | URL of the original user’s photo |
timeclock_qr_code_url | string | URL of the user’s QR code image |
memberships | array of membership objects | See below for properties |
custom_fields | array of custom field objects | See below for properties |
qualifications | array of qualification objects | See below for properties |
background_check_results | array of background check objects | See below for properties |
Membership Properties:
Property | Type | Description / Notes |
organization_member_id | integer | Unique identifier of membership object |
organization_id | integer | Organization Id |
organization_name | string | Organization Name |
date_created | string | Date membership was created in ISO 8601 UTC format |
date_updated | string | Date membership was updated in ISO 8601 UTC format |
is_administrator | boolean | True if user is part of the administrator module in this organization |
administrator_status | string | Localized Status of user in administrator module (may be null) |
administrator_type | string | Localized type (Full, Module, Limited) of administrator (may be null) |
is_client | boolean | True if user is part of the client module in this organization |
client_status | string | Localized status of the user in the client module (may be null) |
client_date_joined | string | Date joined as client in ISO 8601 UTC format (may be null) |
client_last_status_change | string | Date of last client status change in in ISO 8601UTC format (may be null) |
donor_date_joined | string | Date joined as donor in ISO 8601 UTC format (may be null) |
donor_last_status_change | string | Date of last donor status change in in ISO 8601UTC format (may be null) |
member_date_joined | string | Date joined as member in ISO 8601 UTC format (may be null) |
member_last_status_change | string | Date of last member status change in in ISO 8601UTC format (may be null) |
is_donor | boolean | True if user is part of the donor module is this organization |
donor_status | string | Localized status of the user in the donor module (may be null) |
is_member | boolean | True if user is part of the member module is this organization |
member_status | string | Localized status of the user in the member module (may be null) |
is_volunteer | boolean | True if user is part of the volunteer module is this organization |
volunteer_status | string | Localized status of the user in the volunteer module (may be null) |
volunteer_inactive_status_reason | string | Localized volunteer inactive status reason (may be null) |
volunteer_archived_status_reason | string | Localized volunteer archived status reason (may be null) |
volunteer_last_status_change | string | Date of last volunteer status change in in ISO 8601UTC format (may be null) |
volunteer_notes | string | Volunteer Notes (may be null) |
volunteer_application_form | integer | Volunteer Application Form Number (may be null) |
volunteer_date_joined | string | Date joined as volunteer in ISO 8601 UTC format (may be null) |
volunteer_total_hours | number | Total hours logged for volunteer |
Custom Field Properties:
Property | Type | Description / Notes |
type | string / constant | Type of custom fields: |
value | yes_no (boolean) | True = yes, False = No |
value_id | integer | For drop_down type custom fields only (the id of the selected value) |
custom_field_id | integer | Custom Field Id |
custom_field_name | string | Custom Field Name |
custom_field_category_id | integer | Custom Field Category Id (may be null) |
custom_field_category_name | string | Custom Field Category Name |
Qualification Properties:
Property | Type | Description / Notes |
qualification_id | integer | Qualification Id |
qualification_name | string | Qualification Name |
qualification_expires | boolean | True if qualification is an expiring qualification |
value | string | Text of selected qualification level |
value_id | integer | ID of selected qualification level |
expiry_date | string | Expiry date in ISO 8601 UTC format (may be null) |
Background Check Properties:
Property | Type | Description / Notes |
result_type_id | integer | Result type ID |
result_type_name | string | Result type name |
result_type_expires | boolean | True if result type is an expiring result type |
state | string | Current state of background check for this person |
needs_review_reason | string | String containing the reason that this person needs review (blank if state is not needs review) |
effective_date | date | Date that this background check is effective on |
expiry_date | date | Date that this background check expires (null if it doesn’t expire) |
API Endpoints: Users By ID List
Parameters:
None.
Query Parameters:
{ids} A comma separated list of user ids to retrieve (limit of 250 ids per request).
Response:
An array of user documents. See single user section for description.
Custom Field Files
Enterprise: https://api.betterimpact.com/v1/enterprise/users/{user_id}/custom_fields/{user_custom_field_id}/file
Organization: https://api.betterimpact.com/v1/organization/users/{user_id}/custom_fields/{user_custom_field_id}/file
These URLS are specified as the value of the custom field when custom fields are retrieved as part of a single, or list of users.
Parameters:
Parameter | Description |
{user_id} | The user id of the user the custom field file belongs to |
{user_custom_field_id} | The id of the user custom field value |
Query Parameters:
None.
Response:
The file that was requested, as a byte stream.
API Endpoints: Single Timelog Entry
Parameters:
{id} The ID of the timelog entry to retrieve.
Query Parameters:
None.
Response:
A single timelog entry document. See below.
Property | Type | Description / Notes |
timelog_entry_id | integer | The ID of the timelog entry |
date_created | string | The date created, in ISO 8601 UTC format |
date_updated | string | The date updated, in ISO 8601 UTC format |
timelog_entry_type | string | One of: “Unknown” – It is not known what type of entry this is, “Logged” – This entry was created by logging the time manually, “Timeclock” – This entry was created while stopping a timeclock, “Automatic” – This entry was created automatically. |
date_worked | string | The date that was worked, in ISO 8601 UTC format |
hours_worked | number | The number of hours worked |
approved | boolean | Whether or not the timelog entry is approved |
clock_start_time | string | The date the clock was started, if this is a “Timeclock” type entry, in ISO 8601 UTC format. (may be null, if there was no timeclock activity for this timelog) |
activity_id | integer | The ID of the activity that this timelog entry is for |
activity_name | string | The name of the activity that this timelog entry is for |
activity_category_id | integer | The ID of the activity category that this timelog entry is for |
activity_category_name | string | The name of the activity category that this timelog entry is for |
activity_report_group_id | integer | The ID of the activity report group (if applicable) that this timelog entry is for (may be null) |
activity_report_group_name | string | The name of the activity report group (if applicable) category that this timelog entry is for |
organization_id | integer | The id of the organization that this timelog entry is for |
organization_name | integer | The name of the organization that this timelog entry is for |
user_id | integer | The id of the user that this timelog entry is for |
first_name | string | The first name of the user that this timelog entry is for |
last_name | string | The last name of the user that this timelog entry is for |
created_by_user_id | integer | The id of the user that created this timelog entry (may be null) |
created_by_first_name | string | The first name of the user that created this timelog entry |
created_by_last_name | string | The last name of the user that created this timelog entry |
recorded_feedback_fields | array of recorded feedback fields objects | See below for properties |
Recorded Feedback Field
Property | Type | Description / Notes |
feedback_field_id | integer | The id of the feedback field |
feedback_field_name | string | The name of the feedback field |
value | string or number | The value of the feedback field. Number fields will be number type, all other feedback fields will be string type |
value_id | integer | The id of the value of the feedback field, if the feedback field is dropdown type (optional, not included for fields that are not dropdown type) |
API Endpoints: Timelog entries by filtering
Parameters:
None.
Query Parameters:
Property | Type | Description / Notes |
user_ids | Comma separated list of user ids to return results for | Comma separated list of valid user IDs (integers) Default: All users. |
activity_ids | Comma separated list of activity ids to return results for | Comma separated list of valid activity IDs (integers) Default: All activities. |
activity_category_ids | Comma separated list of activity category ids to return results for | Comma separated list of valid activity category IDs (integers) Default: All activity categories. |
activity_report_group_ids | Comma separated list of activity report group ids to return results for | Comma separated list of valid activity report group IDs (integers) Default: All activity report groups |
page_size | The number of results per page. | 1 to 250, Default: 100 |
page_number | The page number to retrieve. | 0 to *, Default: 0 |
include_recorded_feedback_fields | Whether or not to include recorded feedback fields in the results. | “true” or “false”, Default: “true” |
approved | Filter results to approved only. | “true” or “false”, Default: “true” |
updated_since | This parameter will restrict the results to timelog entries that have changed since the date specified. | DateTimes are required to be in ISO 8601 format (using the format string: “yyyy’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffK”). Please see this documentation for more information: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier. Default: Empty. |
created_from | This parameter will restrict the results to timelog entries that were created after the date specified. | DateTimes are required to be in ISO 8601 format (using the format string: “yyyy’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffK”). Please see this documentation for more information: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier. Default: Empty. |
created_to | This parameter will restrict the results to timelog entries that were created before the date specified. | DateTimes are required to be in ISO 8601 format (using the format string: “yyyy’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffK”). Please see this documentation for more information: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier. Default: Empty. |
worked_from | This parameter will restrict the results to timelog entries that were worked after the date specified. | DateTimes are required to be in ISO 8601 format (using the format string: “yyyy’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffK”). Please see this documentation for more information: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier. Default: Empty. |
worked_to | This parameter will restrict the results to timelog entries that were worked before the date specified. | DateTimes are required to be in ISO 8601 format (using the format string: “yyyy’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffK”). Please see this documentation for more information: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier. Default: Empty. |
organization_ids | ENTERPRISE ENDPOINT ONLY. Comma separated list of organization IDs to return results for. | This will return all timelog entries that belong to any of the organizations passed. Comma separated list of valid organization IDs (integers) Default: All organizations in the enterprise. |
Response parameters:
Property | Type | Description |
Header | Object. See below for properties. | Header information related to paging and result set. |
TimelogEntries | Array of timelog entry objects. See single timelog entry section for property descriptions. | A list of the timelog entries that match the query parameters. |
Header Properties:
Property | Type | Description |
first_item_on_page | integer | The 1 based index of the first item in the returned page of the timelog entries collection. |
has_next_page | boolean | True if there is more pages to be returned. |
has_previous_page | boolean | True if there is pages before the returned timelog entries collection. |
is_first_page | boolean | True if returned collection is page 1. |
is_last_page | boolean | True if returned collection is the last page. |
last_item_on_page | integer | The 1 based index of the last item in the returned page of the timelog entries collection. |
page_count | integer | The number of pages in the timelog entries collection. |
page_number | integer | The number of the page returned. |
page_size | integer | The size of the page returned. |
total_items_count | integer | The total number of timelog entries that match the query parameters across all pages. |
API Endpoints: Timelog entries by ID list
Parameters:
None.
Query Parameters:
{ids} A comma separated list of timelog entry ids to retrieve (limit of 250 ids per request)
Response:
An array of timelog entry documents. See single timelog entry section for description.