API

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 

Parameters

None. 

Query parameters

 ParameterDescription Valid Values/Defaults 
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_ 
custom_fields 
Whether or not to include custom fields in the results. “true” or “false” 
 
Default: “true” 
include_ 
qualifications 
Whether or not to include qualifications in the results. “true” or “false” 
 
Default: “true” 
include_ 
memberships 
Whether or not to include membership information in the results. “true” or “false” 
 
Default: “true” 
include_ 
verified_volunteers_ 
background_check_ 
results 
Whether or not to include Verified Volunteers background check information in the results. “true” or “false” 
 
Default: “true” 
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) 
 
Default: All organizations in the enterprise. 
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: 
volunteer / vol 
client / cli 
member / mem 
donor / don 
administrator / admin 
 
Default: All modules. When left out, the modules will be inferred by any {module}_status parameters specified.  
admin_status A comma separated list of the admin statuses you would like to restrict the results to.  active 
inactive 
 
Default: All statuses. 
client_status A comma separated list of the client statuses you would like to restrict the results to. applicant 
inprocess / in_process 
accepted 
inactive 
archived 
 
Default: All statuses. 
donor_status A comma separated list of the donor statuses you would like to restrict the results to. prospect 
active 
inactive 
archived 
 
Default: All statuses. 
member_status A comma separated list of the member statuses you would like to restrict the results to. applicant 
inprocess / in_process 
accepted 
inactive 
archived 
 
Default: All statuses. 
volunteer_status A comma separated list of the volunteer statuses you would like to restrict to.  
 
You may use “archived” to include all archived sub-types and “inactive” to include all inactive subtypes. 
 
applicant 
inprocess 
accepted 
inactiveshortterm 
(or: inactive_short_term) 
inactivelongterm 
(or: inactive_long_term) 
archiveddidntstart 
(or: archived_didnt_start) 
archivedrejected 
(or: archived_rejected) 
archiveddismissed 
(or: archived_dismissed) 
archivedmoved 
(or: archived_moved) 
archivedquit 
(or: archived_quit) 
archiveddeceased 
(or: archived_deceased) 
archivedother 
(or: archived_other) 
 
Default: All statuses. 
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
 
Default: Empty. Will return all profiles regardless of their last update. 

Response parameters: 

Property Type Description 
HeaderObject. 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 

Enterprisehttps://api.betterimpact.com/v1/enterprise/users/{user_id

Organizationhttps://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 
pronounsstringPronouns
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: 
yes_no 
short_text 
number 
long_text 
file 
drop_down 
date 
check_box 
value 
(varies based on type property) 
yes_no (boolean) 
 
short_text (string) 
 
number (number) 
 
long_text (string) 
 
file (string) 
 
drop_down (string) 
 
date (string) 
True = yes, False = No 
 
 
string 
 
 
may be a decimal 
 
 
string 
 
 
URL of the file resource on the API 
 
text of selected value 
 
 
Date in ISO 8601 UTC format 
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

Enterprise: https://api.betterimpact.com/v1/enterprise/by_id_list/users?ids={ids}

Organization: https://api.betterimpact.com/v1/organization/by_id_list/users?ids={ids}

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 

Enterprisehttps://api.betterimpact.com/v1/enterprise/users/{user_id}/custom_fields/{user_custom_field_id}/file 

Organizationhttps://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

Enterprise: https://api.betterimpact.com/v1/enterprise/timelog_entries/{id}

Organization: https://api.betterimpact.com/v1/organization/timelog_entries/{id}

Parameters:

{id}    The ID of the timelog entry to retrieve.

Query Parameters:

None.

Response:

A single timelog entry document. See below.

PropertyTypeDescription / 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 objectsSee below for properties

Recorded Feedback Field

PropertyTypeDescription / Notes
feedback_field_id      integer         The id of the feedback field
feedback_field_name    string          The name of the feedback field
value                  string or numberThe 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

Enterprise:  https://api.betterimpact.com/v1/enterprise/timelog_entries

Organization: https://api.betterimpact.com/v1/organization/timelog_entries

Parameters:

None.

Query Parameters:

PropertyTypeDescription / Notes
user_ids                           Comma separated list of user ids to return results forComma separated list of valid user IDs (integers)   Default: All users.
activity_ids                       Comma separated list of activity ids to return results forComma separated list of valid activity IDs (integers)   Default: All activities.
activity_category_ids              Comma separated list of activity category ids to return results forComma 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 forComma 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 
HeaderObject. See below for properties. Header information related to paging and result set. 
TimelogEntriesArray 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

Enterprise: https://api.betterimpact.com/v1/enterprise/by_id_list/timelog_entries?ids={ids}

Organization: https://api.betterimpact.com/v1/organization/by_id_list/timelog_entries?ids={ids}

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.

Updated on May 14, 2024

Was this article helpful?

Related Articles