List Management - Setting Up HRIS API

ContactMonkey allows internal communications teams to create & deliver campaigns to your existing distribution lists. Although this is an excellent option for many customers, some Internal Communications teams do not have control over their lists, and existing lists may not be adequate for successful communication strategies. 

Please visit our Introduction to List Management page for more information

Introduction to HRIS API

ContactMonkey's List Management solution allows for integration with a broad range of HRIS systems through its API integration.  The API integration allows for a nightly synchronization of data between a customer's HRIS system (BambooHR, Success Factors, etc) and synchronizes user information and data to ContactMonkey so customers can fully utilize the power of the ContactMonkey List Management functionality.

Customers have control of what data is synchronized over, and end users do not have to worry about stale data, as long as data within the originating HRIS system is up to date.

It is important to call out that not all HRIS API connections are created equal. There are Advanced HRIS systems that that have built-in tools for automating API calls (e.g. UKG Pro, Success Factors) and Basic HRIS systems that require a developer to create and manage the code for API calls to ContactMonkey (Dayforce, ADP, Paycor, etc.). 

Before making the decision to sync up your HRIS system with ContactMonkey via our API integration, it is recommended that you understand first if you are leveraging an Advanced HRIS or Basic HRIS system so that you understand the level of technical resources that will be required of your organization to complete the integration. 

Setting Up the API Connection

Customer's ContactMonkey Account Administrator/Owner Tasks

Below are tasks to be carried out normally by customer users who have Administrator/Owner privileges.

1. Request your organization ID (org_id) from your account manager (numbers only).
   
2. Within your HRIS system, determine the directory user fields that will help with generating your future communications.  Customers are asked to schedule the information to be sent to the API endpoint.  This information can be posted to ContactMonkey as CSV through the API endpoint once every 24 hours.
   1. Teams should consider data that will help with generating dynamic lists and also mail merge fields for customized emails to be included in the synchronization
   2. It is highly suggested that all users have these fields be mandatory within your HRIS to provide the best experience with the List Management function
   3. Fields that may be useful in categorizing Campaign Stats should also be a factor
   4. The data will be sent to our endpoint in CSV format. (See below for an attached sample)
      
      
      1. Email is a required field. All other fields are optional.  It must be the first field in the sequence.
      2. In the sample file, sample columns/data  Departments, Title, and Location are not required, and additional columns can be created
         
3. Create an API Key from your ContactMonkey application. ContactMonkey Owner or Admin role is required on the customer's account to generate an API Key
   
   1. Log in to the ContactMonkey Dashboard
   2. Click on your Name in the upper right corner -> Settings -> Integrations -> List Management API and then generate the key from there
      
      
   3. Store the API key safely, once generated, as it can not be revealed again.  The team working on the API integration will need the key to be able to set up the connection from the HRIS system to ContactMonkey.

Customer's HRIS Administrator Tasks

Below are tasks to be carried out normally by a customer's HRIS administrator.  For example, the Success Factors administrator.

ContactMonkey API Workflow 

ContactMonkey has provided a single endpoint for the List Management API.

Administrators will need to set up an HTTP request to this endpoint once every 24 hours with an updated list of contacts and relevant information, which will then be added to the ContactMonkey Contacts directory.

Each time the API is called, the CSV provided in the request will overwrite the previously saved CSV in the ContactMonkey system.

This will mean that any changes made in the ContactMonkey directory that are not reflected in the HRIS will be overwritten once a sync has occurred.

The latest CSV will be processed asynchronously by our application daily. When the CSV is processed, our application will perform the following:

• Create any new contacts that are not in your ContactMonkey directory already. 
• Update the fields of any contacts already using the field data in your latest CSV.
• Delete contacts from your ContactMonkey directory not in the latest CSV. 
• Columns appended to the latest CSV will create fields for all contacts.
• Columns removed from the CSV will result in those columns being removed from the ContactMonkey directory.

API Properties

*The only header required by ContactMonkey is the Bearer Authentication.  The API key contained within the Bearer Authentication is used to authenticate against the ContactMonkey endpoint. Please send the API key generated in the above step to the Authorization header

Request Body 

The ContactMonkey endpoint has two required input parameters, an org_id (integer) and a CSV (file). Both Parameters are required.

Org_id - Integer, required 

• The ID of your organization on the ContactMonkey platform, which was requested in an earlier step
• The ContactMonkey customer success manager can provide this information if it is missing. 

CSV- File, required 

• Provide the CSV file you wish to sync to the ContactMonkey directory.
• The first line in the CSV file must include the field headers. 
• The headers must include the “Email” column.
  • The CSV file information should have been created in the step above when determining the field values that are important to the Customer's team.

When setting up the CSV file to use for the API sync, we have default fields within ContactMonkey that we will map to based on fields received via the API sync. The below table outlines what default fields we will map to and what the field names should be called (column headers in the CSV file) when syncing with ContactMonkey. 

Please note that some fields that are mapped via the API will be considered "data sets" in ContactMonkey, which will change your list filtering options when selecting those fields. Please see the below table for more information on what fields are considered to be "data sets" or not. 

If you map over a field that is not a data set, you would have access to the standard list filtering options:

Whereas if you map over a field that is considered to be a data set, your filtering options would change where you are now allowed to select from all of the values that were synced over: 

Referencing the above table, the column on the right is exactly what the column headers should be called in the CSV file for the API sync. Please follow proper casing in order to have the fields correctly mapped to ContactMonkey defaults (the column on the left). 

API Responses and Basic Troubleshooting

Success Responses 

HTTP Code: 201 

• This code is returned when this is the first API import for your organization. 
• The import will be run immediately. 

HTTP Code: 202 

• This code will be returned when this is a subsequent API import for your organization.
• The import will be run overnight. 

Error Responses

HTTP Code: 403 

• If the token provided does not match the  org_id. 
• No response body is given.

 HTTP Code: 404 

• The org_id parameter did not match our records 
• Also possible that region that your ORG_ID is residing in, is incorrect.  Please check the correct API HTTP Request URL is being used
  JSON response:
  

  {
       "error": "not_found", "error_message": "That organization is not found" 
  } 

HTTP Code: 422 

This error code can occur for several reasons.

• The org_id parameter was not included/missing
  JSON response:
  

  { 
       "error": "unprocessable_entity", 
       "error_message": "Please provide an 'org_id' param" 
  }

• The bearer token in the authorization header was not included:
  JSON response:
  

  { 
       "error": "unprocessable_entity", 
       "error_message": "Please provide an org token"
  }

• The CSV file was not included
  JSON response:
  

  { 
       "error": "unprocessable_entity", 
       "error_message": "Please provide a CSV as a 'csv' param"
  } 

• Returned if the CSV is not valid due to encoding or formatting issues with the CSV, or if the required column was not included.
  JSON response:
  

  { 
       "error": "unprocessable_entity", 
       "error_message": "Couldn't parse the CSV, or CSV file didn't have an Email column" 
  } 

Sample cURL Request

Customer HRIS Administrators looking to troubleshoot can also utilize cURL commands to test the validity of the connection.

Below is a sample of a cURL command that can be run on a fictional customer account:

• Your API Token: <token>
• Your organization ID: 12345  
• The location of your CSV: /path/to/directory-2023-01-01.csv 

curl -v -X POST 'https://contactmonkey.com/public_api/v1/lm_imports' \
  -H "Authorization: Bearer <token>" \
  -F org_id=12345 \
  -F "csv=@/path/to/directory/CMContacts.csv" 

Example Process

Please note that this is one method of uploading the CSV file to ContactMonkey.  Customers can utilize other methods, such as Python and JavaScript, and run the process in the cloud.  The purpose of the example is to show a functioning method for uploading the CSV to ContactMonkey.  An organization's IT team can usually assist with this process.

1. The customer's HRIS system saves the CSV file to a local server location on the customer's internal network.
2. The CSV file is then sanitized for any sensitive information that should not be sent to ContactMonkey/should not be seen by others within the organization who may be creating custom lists/using ContactMonkey.
3. Customer has a scheduled job (also known as a cronjob) to run the curl command as a script at a particular time every day (e.g. 2am local)

   curl -v -X POST 'https://contactmonkey.com/public_api/v1/lm_imports' \
   -H "Authorization: Bearer <token>" \
   -F org_id=12345 \
   -F "csv=@/path/to/directory/CMContacts.csv"