While Pushpay ChMS has a premier, built-in integration with Checkr, this document will show you how to replicate key features of that integration using our API. This allows church administrators to see and manage the status of background checks from your service directly within an individual's profile.

Authentication

Before making any API calls, you must authenticate your application. Our APIs use two different security schemes:

• ChMS API v1 uses HTTP Basic Authentication. You will need to obtain an API username and password from the church's ChMS settings.

• ChMS API v2 is secured with OAuth 2.0. You must first request API credentials by filling out this form to receive OAuth credentials. Our implementation supports both a System Auth flow for church-wide data access and an Identity Auth flow for requests on behalf of an individual user.

Feature Comparison Table

The Integration Workflow

Unlike the built-in Checkr integration, where admins can order a background check from a person's profile, a custom API integration works by having your system push data into the ChMS.

The typical workflow for ChMS API v2 is as follows:

1. A church administrator clicks a URL link from within an individual's profile page (Pushpay ChMS), which launches a webpage to your vendor portal.

2. A church administrator orders a background check through your vendor portal or application.

3. Your system calls the ChMS API v2 to create a new background check record for that individual, and sets the status to PENDING.

4. As the background check progresses in your system (e.g., moves to "CLEAR" or "CONSIDER"), your system sends updates to the ChMS API to change the status of that record.

5. The ChMS administrator can then view the status of the background check on the individual's profile page and use the People Search tool to filter individuals based on their background check status.

Managing Background Check Records (API v2 only)

The core functionality for managing background checks is available exclusively through the ChMS API v2.

Creating a Background Check Record

When a background check is initiated in your system, create a corresponding record in the ChMS.

• Endpoint: POST /individuals/\{id\}/background_checks
• Method: POST
• Key Parameters in the request body:
  • package_name (string): The name of the package, which will be visible in the ChMS UI (e.g., "Volunteer Basic").
  • package_slug (string): A machine-readable version of the package name (e.g., "volunteer_basic").
  • report_status (enum): The initial status of the check. This must be one of the accepted values, such as CLEAR, CONSIDER, PENDING, or SUSPENDED.
  • completed_date (datetime): The date the background check was completed. The expiration_date is automatically set to three years from this date.

Example Request Body:

{
  "completed_date": "2025-01-16T11:52:50.375Z",
  "package_name": "Story Teller",
  "package_slug": "storyTeller",
  "report_status": "PENDING"
}

Valid Report Status Values:

• PENDING
• CLEAR
• CONSIDER
• DISPUTED
• DISPUTED_CLEAR
• SUSPENDED
• CANCELED
• CLEAR_CANCELED
• CONSIDER_CANCELED
• COMPLETE
• PRE_ADVERSE_ACTION
• POST_ADVERSE_ACTION

Updating a Background Check Record

When the status of a background check changes, update the record in the ChMS.

• Endpoint: PUT /individuals/background_checks/\{id\}
• Method: PUT
• Key Parameter in the request body:
  • report_status (enum): The new status of the background check (e.g., changing from PENDING to CLEAR).

The status you set via the API will appear in the "Background Checks" widget on an individual's profile page. Any active record, regardless of status, is considered valid for the purposes of the Schedules feature, unless it is expired.

Example Request Body:

{
  "report_status": "CLEAR"
}

Deleting a Background Check Record

If a background check needs to be removed entirely, you can delete the record.

• Endpoint: DELETE /individuals/background_checks/\{id\}
• Method: DELETE

Profile Order Link: Using Custom Fields (API v1 & v2)

To provide a direct link back to order a background check and/or to the full report on your website, you can use a custom text field. This method adds a new field to the "Custom Fields" section of a person's profile rather than the dedicated "Background Checks" widget.

Step 1: Create a Custom Field Label (API v1 or UI)

A ChMS administrator must first create a custom text field label. This can be done in the UI under Settings > Customizable Fields or via the API v1. This functionality is not available in API v2.

• API v1 Endpoint: update_custom_field_labels
• Method: POST
• Key Parameters:
  • udf_ind_text_#_label (string): The name of your custom field (e.g., "Story Teller Training"). Note that there is a system-wide limit of 12 custom text fields.

Step 2: Add a Link to an Individual's Profile

Once the label is created, you can update the field for a specific individual to include a hyperlink to the report on your service.

ChMS API v2 Endpoint: PUT /individuals/\{id\}

In the request body, include the custom_fields object with the appropriate field name and value, such as:

{
  "custom_fields": [
    {
      "name": "Story Teller Training",
      "value": "<a href='https://yourservice.com/report/123'>View Report</a>"
    }
  ]
}

ChMS API v1 Endpoint: update_individual

Use the udf_text_# parameter corresponding to the label you created, passing the HTML anchor tag as the value.

To stay within the 100-character limit for this field, it is highly recommended to use a URL shortening service.

Feature Comparison

This table summarizes the key differences in functionality between the Checkr integration and what is achievable via the ChMS API.

Appendix: Technical Details

Checkr User Experience within Pushpay ChMS

Integration Settings

In the Pushpay ChMS, the Settings > Integrations page allows the admin to manage the built-in integrations. These are integrations that are developed and maintained by Pushpay.

Checkr: Order from Individual Profile

One of the built-in ChMS integrations is Checkr, which allows the admin to order background checks on an individual from their profile page: People Search > individual > Actions > Order Background Check

Reference: How to Set Up the Appropriate Privileges for Background Checks

After selecting the order action, the admin can choose a "package" for the background check(s).

A toast message is displayed to confirm to the admin that the background check has been requested. The individual will receive an email request to approve the background check on their information.

On the profile page for the individual, the About tab has a widget with the status of all background checks for this person.

The admin must have the "Background Check" permission to order the background check for an individual, and to view the status and results of that background check. Admins with Full Read People Permissions will also be able to see the background check detail tile (widget) on a profile, however they will only be able to see:

• Background check exists
• Type of check
• Date completed
• Date expires

People Search Filters

The People Search has a full-featured set of filters to find people and create reports. One of those filters is the Background Check Package.

Reference: How to Create and Save a People Search

• The list of background check packages can be modified by the ChMS API.
• The list of values for the Report Status is fixed.

Schedules

Pushpay ChMS makes it easy to manage volunteers and serving rotations for ministries that have regular schedules. It is common for a ministry to have background check requirements, especially in children's and nursery ministries.

Reference: FAQ - Schedules

When creating a team within Schedules, the admin can define which background check is required for a specific position (serving role) within the team.

Reference: Learning about Schedules

By using the background check feature, a scheduler can see which volunteers are compliant or not compliant with the background check needs of a specific volunteer position.

Reference: How do I see blockouts, preferences and conflicts when scheduling volunteers?

Important Notes:

• After an existing background check has passed the expiration date, that check will be shown on the individual profile under the section "Expired Checks".
• Expired background checks will appear as expired within schedules, so that a scheduler can see the volunteer alert.
• The Auto-schedule feature will not add a volunteer to a schedule with either a missing or expired background check.
• However, a scheduler admin can manually add a volunteer to a schedule position after confirming that the background check is missing.

Custom Background Check: Individual Profile

• Any record of the background check is interpreted as "valid", as long as the check has not passed the expiration date.
• The Schedules page will show that the volunteer is missing the necessary background check; only when all records of the background check are missing from the DB.
• Keep in mind that any record, and any status, for a background check will show as valid within the Schedules system. Only missing or expired background checks will show an alert for the volunteer within the Schedules feature.
• The People Search feature will also show the custom background check package_name as an option for the Background Check Package filter.
• It is possible for an individual to have multiple records for the same background check type (package_name, package_slug within the API). The expired check will be shown under "Inactive Checks" when there is also a valid, active record.
• The Schedules feature will show an expired status for a custom background check, after the expiration date.

API Guide: Custom Background Checks

Setup Steps

1. Create a custom (individual profile) field within the web app UI, marked for Admins only "Only people admins can view and edit".

   • Getting Started with Custom Fields
   • How to Create or Edit Custom Fields
   • Learning about Additional Profile Fields

2. Important Note: The custom text field labels cannot be updated in ChMS API v2; that is only available in API v1.

3. Important Note: There are a maximum of 12 People Text labels that can be used within the ChMS system, which may already be used by the church for other purposes.

4. Add a URL link to the individual profile custom field (limited to 100 chars) via the API:

   • ChMS API v2: Update Individual
   • ChMS API v1: Update Individual

5. A ChMS admin can update the field manually within the web application UI, or the API provides access to update the custom field value for each profile within the ChMS.

6. The individual profile page now shows the custom field and links. Use tiny URL links to help stay within the 100 character limit.

7. Could update the link from "order" to "View" after completion of the background check.

API Endpoints Reference

ChMS API v1

/custom_field_labels

Documentation

/update_custom_field_labels

Documentation

/update_individual

Documentation

/individual_profiles

Documentation

/individual_profile_from_id

Documentation

/add_individual_to_queue

Documentation

/individual_queues

Documentation

/process_list

Documentation

ChMS API v2

GET /church/custom_fields

Documentation
Retrieve custom field definitions for the church.

POST /individuals

Documentation
Create a new individual in the ChMS.

GET /individuals

Documentation
Retrieve a list of individuals.

GET /individuals/{id}

Documentation
Retrieve a specific individual by ID.

PUT /individuals/{id}

Documentation
Update an individual's profile, including custom fields.

POST /queues/{id}/individuals

Documentation
Add an individual to a process queue.

GET /processes

Documentation
Retrieve process queue definitions.

GET /individuals/background_checks

Documentation
Retrieve all background checks in the system.

GET /individuals/{id}/background_checks

Documentation
Retrieve background checks for a specific individual.

POST /individuals/{id}/background_checks

Documentation
Create a new background check record for an individual.
Valid Report Status Values:

• PENDING
• CLEAR
• CONSIDER
• DISPUTED
• DISPUTED_CLEAR
• SUSPENDED
• CANCELED
• CLEAR_CANCELED
• CONSIDER_CANCELED
• COMPLETE
• PRE_ADVERSE_ACTION
• POST_ADVERSE_ACTION

PUT /individuals/background_checks/{id}

Documentation

Update a background check record.

Note: The "expiration_date" is hardcoded to three years past the "completed_date".

DELETE /individuals/background_checks/{id}

Documentation

Delete a background check record.