Skip to main content

Sapling - Connecting your ATS to Sapling with the Sapling Public API

Bolaji Elusogbon
Updated

Introduction

This article explains how an Applicant Tracking System (ATS) can integrate with Sapling through the Sapling Public API. This applies to all ATS vendors with whom Sapling does not have a formal partnership and out-of-the-box integration in place.

The goal of this integration is to pass candidates who have been hired into Sapling as “pending hires” so that their Sapling onboarding experience can be launched by the People Ops team.

 

Requirements

Building an integration between an ATS solution and Sapling includes the following prerequisites:

  • Mutual customer - the mutual customer is who provides the necessary API keys
  • Developer experience - you’ll be running calls against the Sapling Public API 
  • Integration request form completed - complete this form so the Sapling team can provide support where needed as you build the integration

 

Solution Options

There are two routes you can take with this integration, depending on the level of data sharing requested by our mutual customer. Both routes are effectively “listening” for candidates marked as hired in the ATS solution, then calling the Sapling Public API to insert that candidate into the Sapling Pending Hires bay.

  • Option 1: Baseline Data Feed - passes a minimal set of candidate data into Sapling
    • 1 call to the Sapling Public API
    • Likely minimal changes needed within the ATS solution itself
  • Option 2: Full Data Feed - passes any or all candidate data into Sapling
    • Multiple calls to the Sapling Public API
    • Changes likely required within the ATS solution for field mapping

Kallidus_v1_Integrations_-_Passing_candidate_data_into_Sapling_via_Public_API.jpg

Option 1: Baseline Data Feed

  1. Secure the full Sapling domain (e.g. customername.saplingapp.io or customername.kallidus-suite.com/hr ) and API keys from our mutual customer
  2. Build a solution for listening or polling the ATS itself to know when candidates are moved to the “hired” stage (or similar equivalent stage)
  3. When a candidate is moved to the “hired” stage, call the POST method on the Sapling Public API Pending Hire resource
    1. Sapling will return a success or failure message that also includes the User GUID (user_guid)
      1. user_guid allows the ATS provider to make additional calls if needed against the Users resource (see Full Data Feed below)
    2. If the call is successful:
      1. The candidate will show up in the Sapling Pending Hires bay immediately
      2. If the candidate is a duplicate (based on email address) with another user already in Sapling, the Sapling super admin user will be able to resolve that duplication through the Sapling Pending Hires bay
    3. If the call fails:
      1. The ATS provider will need to manage resending the call to Sapling after correcting whatever issue caused the failure

 

Option 2: Full Data Feed

  1. Follow steps 1-3 under Baseline Data Feed above, then...
  2. Build a solution for mapping fields from the ATS solution with fields from Sapling (calling the Fields resource for the currently available fields from Sapling)
  3. When a candidate is successfully sent to Sapling and you receive the user_guid (step 3a above), call the PUT method on the Sapling Public API Users resource to update additional fields from the ATS solution based on the mapping you’ve created
    1. Sapling will return a success or failure message
    2. If the call is successful:
      1. The candidate’s additional data will be updated in Sapling immediately
      2. If the candidate’s onboarding hasn’t started, that additional data can be used in workflows, emails, and document signature requests within Sapling
    3. If the call fails:
      1. The ATS provider will need to manage resending the call to Sapling after correcting whatever issue caused the failure

 

Frequently Asked Questions

What kind of support is available when building this integration?

Sapling provides full support for the Sapling Public API itself and is unable to provide troubleshooting support for development work outside of Sapling that interacts with the Sapling Public API. We’re nice humans though and will always try to help you out if you run into a challenge connecting to our API.

 

What kind of metering or call limits are in place on the Sapling Public API?

Use of the Sapling Public API is subject to Sapling’s Fair Use clause within the Sapling customer Master Service Agreement MSA §3(c). In short, use beyond reasonable levels allows Sapling to limit use without advance warning. If you’re unsure of your calling impact, connect with our Integrations team to discuss your implementation.

 

How will we be notified of changes to the Sapling Public API structure?

The Sapling Public API is currently under beta routing so changes may occur without advance notice. While we intend to keep most changes backward compatible and all changes will be reflected in our documentation, breaking changes are possible. Reach out to our Integrations team if you need additional assistance.

 

What fields are included in Option 1: Baseline Data Feed?

Review the example POST method on the Users resource; for example:

firstName="Candidate"
lastName="Test4"
personalEmail="ct4@gmail.com"
startDate="2021-07-21"
department="Finance"
source="www.lever.com"
preferredName="Joe"
employmentStatus="Full Time"
jobTitle="Junior Accountant"
location="London"
status="active"

 

How frequently do API Keys expire?

API Keys to the Sapling API expire every 90 days. These keys can easily be regenerated inside Sapling itself.

 

What happens if we pass a hired candidate into Sapling multiple times?

If the hired candidate’s email address hasn’t changed, Sapling’s Pending Hires bay will flag the potential duplicate. Super Admin users in Sapling can then choose how to resolve the duplicate directly in Sapling (ignoring, merging data, overwriting data, etc.).

If the hired candidate’s email address has changed, that will appear as a new user in the Sapling Pending Hires bay. While not flagged as a potential duplicate, Super Admin and Admin users in Sapling can delete that unnecessary user record directly in Sapling.

 

How can I connect with the Integrations team for additional help??

You can reach our Integrations team through email: integrations@trysapling.com

 

Related articles