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 option.
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.
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.
- Request your organization ID (org_id) from your account manager.
- 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.
- 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
- 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
- Fields that may be useful in categorizing Campaign Stats should also be a factor
- The data will be sent to our endpoint in CSV format. (See below for an attached sample)
- Email is a required field, all other fields are optional.
- In the sample file, sample columns/data Departments, Title, and Location are not required, and additional columns can be created
- 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
- Log in to the ContactMonkey Dashboard
- Click on your Name in the upper right corner -> Settings -> Integrations -> List Management API and then generate the key from there
- 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.
HTTP Request URL
|Authorization Header Format
|Authorization: Bearer <token>
*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
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.
API Responses and Basic Troubleshooting
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.
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
"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
"error_message": "Please provide an 'org_id' param"
- The bearer token in the authorization header was not included:
"error_message": "Please provide an org token"
- The CSV file was not included
"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.
"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 \