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. 1 to * 
 
Default: 1 
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 
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) 

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. 

Updated on March 30, 2021

Was this article helpful?

Related Articles