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 

• Enterprise: https://api.betterimpact.com/v1/enterprise/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    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
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 

Enterprise: https://api.betterimpact.com/v1/enterprise/users/{user_id} 

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
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 

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.