IT

API Keys 

Important: The target audience for this topic is Technical and IT staff in your organization. 

Create a New API Key 

  1. Go to: Configuration, then click on “Security Settings” found in the sidebar under Organization Settings 
  1. Scroll down to API Keys section 
  1. Click the [+ Create API Key] button 
  1. Optional: Check the “Enabled” box so that the API key will be able to access your account’s information 
  1. Check the appropriate Modules checkbox(es). This controls the modules that any applications that use this API key will have access to. For example, by choosing Volunteer, applications that use this key will be able to see Volunteers when listing users. 
  1. Click the [Create API Key] button. A username and password will be created for the API Key. 

The [Options] button to the left of an existing API Key will give you the ability to Edit or Delete that key. 

Note: You can control access to Manage API Keys for Limited Access Admins. 

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. 

General Email Troubleshooting and Tips 

Troubleshooting 

  • Make sure the email address is entered properly in the recipient’s profile. For example, is the domain (e.g. @gmail.com) spelled properly? Are you missing a period (.) or underscore (_) in the email address? 
  • Have you received a bounce notification from postmaster@volunteer2mail.com? If so, what did the message say? Typical messages that indicate the email address has not been entered properly (or no longer exists) will usually include messages such as: “no such user”, “unable to relay for user”, “this mailbox does not exist”, “email address could not be found, or was misspelled”, etc. 
  • Has the recipient checked their junk or spam folder? If the message is ending up here, you may want to read the “Tips for keeping emails to your recipients from getting trashed or spam filtered” section of this article (next section)

Tips to avoid emails ending up in recipient trash or spam folders 

  1. Only send mail to the people that ought to receive it  
    • Yahoo’s mail service reminds us that spammers write to many people who don’t want their mail, so their anti-spam filters are designed to identify that behavior.  One of the patterns they consider in identifying a spammer is too high a percentage of respondents that choose to move the email to the spam folder. 
    • To avoid being perceived as a spammer, don’t send out one email to all people containing many different messages intended for different groups of people. Filter that list to send only the pertinent information out to the right people in each email. Recipients would rather receive two emails with separate messages where both pertain to them, than one long email with a mishmash of information, some of which has nothing to do with them. 
  1. Avoid spam-triggering words and phrases 
    • One of our clients had an email treated as spam by more than one of the large internet mail providers because she included the phrase “Free tickets”. It was a totally legitimate offer she was making to her people, but too many spammers have used similar wording. 
    • Sendgrid.com tells us that “Unfortunately, there is no complete list of spam trigger words. Further, it is not always the case that your email will end up in the spam filter simply by using a so-called trigger word. The key thing to remember is that a spam filter is trying to remove commercial advertisements and promotions. So generally, words that are common in such emails should be avoided or used sparingly.” There are a variety of sites that detail spam trigger words and phishing phrases to avoid in subject lines. 
  1. Use subject lines that let the recipient know what the email is about 
    • So, if your email gets past the spam filters, you still have to prevent it from being mistaken for spam or unnecessary information and deleted without so much as a glance. 
    • Mindtools.com suggests that we treat subject lines a little like newspaper headlines. “A newspaper headline has two functions: it grabs your attention, and it tells you what the article is about, so that you can decide if you want to read further. Email subject lines need to do exactly the same thing! Use a few well-chosen words, so that the recipient knows at a glance what the email is about. Of course, just as it would be ridiculous to publish a newspaper without headlines, never leave the subject line blank. Emails with blank subject lines are usually spam!” 
    • Mail Chimp analyzed over 40 million emails sent from customers and found that 9 of the top 10 highest open rates had the company name in it 
    • Examples: 
      • Really Bad – Subject: Free donuts 
      • Bad – Subject: Free donuts at orientation 
      • Good – Subject: Applicant orientation 10:00 this Thursday 
      • Very Good – Subject: Anytown Museum applicant orientation 10:00 this Thursday 
  1. Avoid Large Attachments and Certain Attachment Types 
    • In general, .jpg, .gif, .png and .pdf attachments are safe to send, provided you include some content in the email as well. However, executable attachments such as .exe, .zip, .swf, etc. should be avoided entirely. 
    • TechRepublic.com suggests “Don’t attach large files to an e-mail; anything over one or two megabytes shouldn’t be sent via e-mail. E-mail attachments consume inordinate amounts of e-mail server space and network bandwidth and are often the culprits behind virus outbreaks.” Because of their link to viruses, emails containing attachments can have a greater chance of being treated as spam if other elements of the email are similar to spam. Many sources online agreed with limiting the file size of attachments, not only in a single attachment but as a total as well. Some email inboxes have limits to their capacity; emails with large attachments can claim too much space to be kept. 
  1. Remove bad addresses from your database 
    • Spammers list typically have a larger percentage of bad email addresses than legitimate lists. One great way to look like a spammer is to include bad email address in your bulk emails, especially when you keep sending to that address. 

Technical Email Information for IT Staff 

SMTP Servers: 

  • Mail Server IP Address: 
    • Primary SMTP Server: 209.15.205.180 
    • Transactional SMTP Server: 198.21.7.99 
  • Reverse DNS (PTR): 
    • Primary SMTP Server: outbound.volunteer2mail.com 
    • Transactional SMTP Server: o2.trans.volunteer2mail.com 
  • Forward DNS (A): 
    • Primary SMTP Server: outbound.volunteer2mail.com 
    • Transactional SMTP Server: o2.trans.volunteer2mail.com 

IMPORTANT
1. volunteer2mail.com is a dedicated domain used to send emails from the Better Impact family of products 
2. We fully support SPF, Sender ID, DKIM and DomainKeys for email being sent from the volunteer2mail.com domain 
3. Our mail server is white-listed and registered in feedback loops with major providers such as Hotmail, Yahoo, AOL and Comcast 
4. Messages are sent with a “Return-Path” header value of bounce@volunteer2mail.com 
5. We utilize a custom service to process and send notifications of bounces that are received at bounce@volunteer2mail.com to notify the original sender of the bounce; this is done in accordance with recommended SPF guidelines 

Our outbound SMTP servers: 

  • Standard emails are sent from: 209.15.205.180 (outbound.volunteer2mail.com) 
  • Transactional emails (password resets, system notifications, etc.) are sent from: 198.21.7.99 (o2.trans.volunteer2mail.com) 

These servers are whitelisted and registered in feedback loops with major providers such as Hotmail, Yahoo and AOL in accordance with bulk-sending best practices. We also continuously monitor the sending reputation of these servers to ensure optimal delivery. 

If possible, it is recommended that you whitelist our outbound mail servers to ensure deliverability. These are both dedicated IP addresses that are used for the sole purpose of sending mail from our application (we do not send any form of advertising or marketing mails from these servers). 

We send all email using opportunistic TLS encryption, meaning it will be sent using TLS if the recipient’s email server supports it. Otherwise, it will be sent in plain text to ensure deliverability. 

When we send mail through our service, the headers are as follows: 

Return-Path: <bounce@volunteer2mail.com> 

From: “Your Name” <you@yourdomain.com> 

To: “Recipient Name” <recipient@theirdomain.com> 

Under some circumstances, to ensure deliverability, we need to use the following headers to send the mail instead (note the addition of the “Reply-To” header and the use of “message@volunteer2mail.com” in the “From” header): 

Return-Path: <bounce@volunteer2mail.com> 

From: “Your Name” <message@volunteer2mail.com> 

Reply-To: “Your Name” <you@yourdomain.com> 

To: “Recipient Name” <recipient@theirdomain.com> 

Reasons why this is done are as follows: 

  • The sender’s domain contains a DMARC (link to: https://dmarc.org/) record with a policy of either: “reject” or “quarantine”. 
  • We detect (via an MX lookup) that the sender’s email is being hosted in Office 365. This is done to avoid message such as “This Sender Failed Our Fraud Detection Checks and May Not Be Who They Appear to Be” from showing to your recipients. 
  • We detect a TXT record in the sender’s domain with the value of “_betterimpact-rewrite-sender”. Note: this can be used to force the use of a “Reply-To” header for your domain in circumstances where the “From” header would cause issues with fraud detection / spoofing in your email environment. 

Typical Email Headers (for reference purposes) 

Return-Path: <bounce@volunteer2mail.com> 
Received: from [209.15.205.180] ([209.15.205.180:65508] 
helo=outbound.volunteer2mail.com) by smtp51.gate.dfw1a.rsapps.net 
(envelope-from <bounce@volunteer2mail.com>) (ecelerity 2.2.3.46 r(37554)) 
with ESMTP id 2F/94-09431-B184BFD4; Fri, 17 Jun 2011 08:27:07 -0400 
DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; 
s=s1024;d=volunteer2mail.com; 
h=from:to:sender:date:subject:mime-version:content-type:message-id; 
bh=wixYDQhFU6dOc6HhkA2YYmdhV0s=; 
b=lapra2B3liMDpfGSzY5TNbXuPIOb8Ep+98dp8+uDLjPmZxElgAo4o5IvdsDbBXfdsLKIMoHf 
bHFKiFmugrV/DnRlTi4RMOK3l+xvtPR8dfrXqcnERQdOKSDNaU6XUnqRFEDj0xNg8s5DsnAW 
WGnVAETTXAYtaraReENUgITtWtY= 
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; 
s=s1024;d=volunteer2mail.com; 
h=from:to:sender:date:subject:mime-version:content-type:message-id; 
b=GGLkdKj1hCa8HE8MS0WLcOONj3IzyfwP7cm8uAbNa1OU762gusqtHlNHI4/XleIv1fwqn2vU 
XoGJa/ElYw691XsDYTlPoyJ0nhnS24CwP6MNa8tUtJQmXmaoEx8+FWRpv3nxfgZK4FFshpF3 
73tj2e15C8Nk04d3jnMO6ieq5eQ= 
Received: from mail pickup service by outbound.volunteer2mail.com with Microsoft SMTPSVC; 
Fri, 17 Jun 2011 08:27:06 -0400 
From: <johndoe@example.com> 
To: <janedoe@example.com> 
Date: Fri, 17 Jun 2011 08:24:46 -0400 
Subject: Subject 
MIME-Version: 1.0 
Content-Type: multipart/alternative; 
boundary=”_=aspNetEmail=_d6ef38fc43584694bd897c3367f0c448″ 
X-Mailer: aspNetEmail ver 3.7.0.10 
Message-ID: <vol2web1697b83fd01bc4e819c576c84dfeccf4e@vol2web1> 

Contacting Support 

If you encounter a bounce message containing information related to spamming, blacklisting, etc. (or other problems you are unable to solve directly), please contact us. 

Webpage not Loading Properly 

If it appears that your webpage did not load fully, it is very likely that there is an issue with your network blocking our content delivery network (CDN). This network is used to send images and style sheets for the Volunteer Impact site. 

Here’s what your login screen might look like: 

Here’s what you can do: 

  • Go to the website: https://app.betterimpactcdn.com/content/images/logo-betterimpact2.png 
  • if you don’t see the Better Impact logo, contact your IT department and have them whitelist the domain: app.betterimpactcdn.com 
  • If you are not able to whitelist the CDN domain / IP address, you can perform a local host override for the CDN domain by pointing app.betterimpactcdn.com to 209.15.232.170 

Technical Specifications 

Note: Very few of our members require implementing the Domain, IP and Email configurations. Your Information Technology Department will know if any of this applies in your case and this document is intended for them. 

Domains and IP Addresses 

Application domains: 

  • app.betterimpact.com 
  • app.betterimpactcdn.com 

IP address for app.betterimpact.com: 

  • 209.15.232.170 

File Manager domain: 

  • content.betterimpact.com. 

Test link to see if you can access the CDN: 

The link above should load the Better Impact logo 

If you are not able to whitelist the CDN domain / IP address, you can perform a local host override for the CDN domain by pointing app.betterimpactcdn.com to 209.15.232.170

Our origin can handle traffic for that domain name as well. 

Timeclock Restrictions 

You can restrict volunteers from accessing the mobile timeclock and also restrict access to the general timeclock unless the time clock is on your network. Add an external IP address or CIDR range into your account by going to Configuration, then clicking on “Hours and Timeclock Settings” found in the sidebar under Activities. 

Google Analytics 

About this feature: You can collect information about the traffic on your public pages by integrating Google Analytics into your organization. You’ll need your own Google account with Google Analytics to use this feature. Your IT team can help you with this and you can provide them the information below to help them get started. 

Set up a Google Account 

  1. Visit https://accounts.google.com/SignUp to create a google account 
  1. Fill out the form and click “Next Step”. Include your mobile number to help secure your account (not required). 
  1. You will get a confirmation email in whatever email you provided in the form. Make sure to follow the link in the confirmation email so that your account is confirmed. 

Set up Your Google Analytics 

  1. Go to the analytics sign up page: https://www.google.com/analytics/web/provision?authuser=0#provision/SignUp/ 
  1. Click the “Sign up” Button 
  1. Fill out the form: 
    • Make sure “Website” is selected at the top. Do not select “Mobile app” 
    • Enter your organization name as the “Account Name” 
    • Enter a name to identify your public page. We suggest something like “{Organization Name} – Public Volunteer Page” 
    • For “Website URL” click on the http:// and change it to https://  then enter “app.betterimpact.com into the bo. 
    • If you would like, you can select an Industry. This helps google generate reports for you 
    • Select your country / timezone 
    • Check and/or Uncheck any of the data sharing options that you would like to include 
    • Click the “Get Tracking ID” button 
  1. Read and Agree to the Terms of Service Agreement. Make sure to select your country to get the appropriate service agreement 
  1. After you click “I Accept” you will be brought to your analytics dashboard!  Copy the tracking Id from the centre of the screen and paste that into the “Tracking ID” box in your general settings 
  1. You are all set! Soon your analytics Dashboard will be filled with statistics for you. Consider book marking https://analytics.google.com so, you can find your analytics again later 

Enable Google Analytics 

  1. Once you have set up Google Analytics, go to Configuration, then click on “Public Volunteer Page Settings” found in the sidebar under Recruitment
  1. Scroll down to the “Configuration” section 
  1. Enter your tracking ID, generated during your Google Analytics setup 
  1. Click the [Save] button 
Updated on January 9, 2021

Was this article helpful?

Related Articles