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

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

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.

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

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

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

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

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.

Importing Donations

API Lookup

November 2024 – 4x.10.0 Update

Survey Responses