IT: API

API Functionality

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

ParameterDescriptionValid Values / Defaults
page_sizeThe number of results per page.1 to 250

Default: 100
page_numberThe 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_idsENTERPRISE ENDPONT 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.
modulesA 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_statusA comma separated list of the admin statuses you would like to restrict the results to. active
inactive

Default: All statuses.
client_statusA 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_statusA comma separated list of the donor statuses you would like to restrict the results to.prospect
active
inactive
archived

Default: All statuses.
member_statusA 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_statusA 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_sinceThis 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:

PropertyTypeDescription
HeaderObject. See below for properties.Header information related to paging and result set.
UsersArray of user objects. See single User section for property descriptions.A list of the users that match the query parameters.

Header Properties:

PropertyTypeDescription
first_item_on_pageintegerThe 1 based index of the first item in the returned page of the users collection.
has_next_pagebooleanTrue if there is more pages to be returned.
has_previous_pagebooleanTrue if there is pages before the returned users collection.
is_first_pagebooleanTrue if returned collection is page 1.
is_last_pagebooleanTrue if returned collection is the last page.
last_item_on_pageintegerThe 1 based index of the last item in the returned page of the users collection.
page_countintegerThe number of pages in the users collection.
page_numberintegerThe number of the page returned.
page_sizeintegerThe size of the page returned.
total_items_countintegerThe 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:

ParameterDescription
{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:

PropertyTypeDescription / Notes
user_idintegerUnique id of user
first_namestringFirst name
last_namestringLast name
legal_first_namestringLegal first name
middle_namestringMiddle name
titlestringTitle (salutation)
suffixstringSuffix
address_line_1stringLine 1 of Address
address_line_2stringLine 2 of Address
citystringCity
zip_codestringZip Code / Postal Code / Post Code
statestringState / Province / County
countrystringCountry
email_addressstringEmail address
secondary_email_addressstringSecondary email address
mobile_email_addressstringMobile email address
home_phonestringHome phone number
work_phonestringWork phone number
work_phone_extstringWork phone number extension
cell_phonestringCell / Mobile phone number
phone_preferencestringPhone preference
twitter_usernamestringTwitter username
linkedIn_profile_urlstringLinkedIn profile URL
Instagram_usernamestringInstagram username
usernamestringUsername
birthdaystringBirthday in ISO 8601 UTC format (may be null)
date_createdstringDate profile was created in ISO 8601 UTC format
date_updatedstringDate profile was last updated in ISO 8601 UTC format
regionstringLocalized Name of the region
region_codestringLanguage code for region
is_groupbooleanDoes this profile represent a group
group_namestringGroup name
photo_url_scaledstringURL of a scaled down version of the user’s photo
photo_url_originalstringURL of the original user’s photo
timeclock_qr_code_urlstringURL of the user's QR code image
membershipsarray of membership objectsSee below for properties
custom_fieldsarray of custom field objectsSee below for properties
qualificationsarray of qualification objectsSee below for properties
background_check_resultsarray of background check objectsSee below for properties

Membership Properties:

PropertyTypeDescription / Notes
organization_member_idintegerUnique identifier of membership object
organization_idintegerOrganization Id
organization_namestringOrganization Name
date_createdstringDate membership was created in ISO 8601 UTC format
date_updatedstringDate membership was updated in ISO 8601 UTC format
is_administratorbooleanTrue if user is part of the administrator module in this organization
administrator_statusstringLocalized Status of user in administrator module (may be null)
administrator_typestringLocalized type (Full, Module, Limited) of administrator (may be null)
is_clientbooleanTrue if user is part of the client module in this organization
client_statusstringLocalized status of the user in the client module (may be null)
client_date_joinedstringDate joined as client in ISO 8601 UTC format (may be null)
client_last_status_changestringDate of last client status change in in ISO 8601UTC format (may be null)
donor_date_joinedstringDate joined as donor in ISO 8601 UTC format (may be null)
donor_last_status_changestringDate of last donor status change in in ISO 8601UTC format (may be null)
member_date_joinedstringDate joined as member in ISO 8601 UTC format (may be null)
member_last_status_changestringDate of last member status change in in ISO 8601UTC format (may be null)
is_donorbooleanTrue if user is part of the donor module is this organization
donor_statusstringLocalized status of the user in the donor module (may be null)
is_memberbooleanTrue if user is part of the member module is this organization
member_statusstringLocalized status of the user in the member module (may be null)
is_volunteerbooleanTrue if user is part of the volunteer module is this organization
volunteer_statusstringLocalized status of the user in the volunteer module (may be null)
volunteer_inactive_status_reasonstringLocalized volunteer inactive status reason (may be null)
volunteer_archived_status_reasonstringLocalized volunteer archived status reason (may be null)
volunteer_last_status_changestringDate of last volunteer status change in in ISO 8601UTC format (may be null)
volunteer_notesstringVolunteer Notes (may be null)
volunteer_application_formintegerVolunteer Application Form Number (may be null)
volunteer_date_joinedstringDate joined as volunteer in ISO 8601 UTC format (may be null)
volunteer_total_hoursnumberTotal hours logged for volunteer

Custom Field Properties:

PropertyTypeDescription / Notes
typestring / constantType 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_idintegerFor drop_down type custom fields only (the id of the selected value)
custom_field_idintegerCustom Field Id
custom_field_namestringCustom Field Name
custom_field_category_idintegerCustom Field Category Id (may be null)
custom_field_category_namestringCustom Field Category Name

Qualification Properties:

PropertyTypeDescription / Notes
qualification_idintegerQualification Id
qualification_namestringQualification Name
qualification_expiresbooleanTrue if qualification is an expiring qualification
valuestringText of selected qualification level
value_idintegerID of selected qualification level
expiry_datestringExpiry date in ISO 8601 UTC format (may be null)

Background Check Properties:

PropertyTypeDescription / Notes
result_type_idintegerResult type ID
result_type_namestringResult type name
result_type_expiresbooleanTrue if result type is an expiring result type
statestringCurrent state of background check for this person
needs_review_reasonstringString containing the reason that this person needs review (blank if state is not needs review)
effective_datedateDate that this background check is effective on
expiry_datedateDate 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:

ParameterDescription
{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.

Looking for something else?