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/

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

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

Parameters:

None.

Query parameters:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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.

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

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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

If Single Sign On is enabled for this user, this field will contain the SSO username. Otherwise this field will contain the username from our system.

single_sign_on_enabled

boolean

Whether or not Single Sign On is enabled for the user.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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.

Tables can't be imported directly. Please insert an image of your table which can be found here.

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

Tables can't be imported directly. Please insert an image of your table which can be found here.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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.

created_from

This parameter will restrict the results to timelog entries that were created after the date specified.

created_to

This parameter will restrict the results to timelog entries that were created before the date specified.

worked_from

This parameter will restrict the results to timelog entries that were worked after the date specified.

worked_to

This parameter will restrict the results to timelog entries that were worked before the date specified.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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:

Tables can't be imported directly. Please insert an image of your table which can be found here.

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.