List Management - Setting Up HRIS API to Sync Employee Contacts

ContactMonkey's HRIS API integration for List Management automatically synchronizes employee data from your HR system to ContactMonkey once every 24 hours (Replace Sync) or once every 2 hours (Upsert Sync). This keeps your contact lists up-to-date without manual imports.

Supported HRIS systems include: BambooHR, SuccessFactors, UKG Pro, Dayforce, ADP, Paycor, and others with API capabilities.

Before You Begin

Time and Resources Required

IT Effort: Medium to High (approximately 30 minutes)

Team Members Needed:

• ContactMonkey Owner or Administrator
• HRIS Administrator or IT team member familiar with API integrations
• (Optional) Developer for Basic HRIS systems

Understanding HRIS System Types

Advanced HRIS Systems (built-in API automation)

• UKG Pro, SuccessFactors
• Have built-in tools for automating API calls
• Can schedule API requests without custom code

Basic HRIS Systems (require custom development)

• Dayforce, ADP, Paycor
• Require a developer to create and manage API call code
• Need scripting or automation platform

Understanding your HRIS type helps you plan the right resources for setup.

How the Sync Works

Your HRIS sends a CSV file to ContactMonkey's API endpoint, which will be processed in one of two modes:

1. Replace Mode (default):
   • Once every 24 hours
   • Adds new contacts not previously in the system
   • Updates existing contact information
   • Removes contacts no longer in your CSV file
   • Creates new fields when you add columns
   • Deletes fields when you remove columns

Important: Each sync completely overwrites your ContactMonkey directory. Any manual changes made in ContactMonkey that aren't in your HRIS will be lost after the next sync.

2. Upsert Mode:
   • Adds new contacts not previously in the system
   • Updates existing contact information
   • Can delete contacts using a special field in your CSV file
   • Creates new fields when you add columns
   • DOES NOT delete fields when you remove columns

Step 1: Get Your Organization ID

Your organization ID (org_id) is a numeric value that identifies your ContactMonkey account.

To obtain it: Contact your Customer Success Manager or the Technical Support team.

Save this number - you'll need it for API configuration.

Step 2: Plan Your Data Fields

Work with your internal communications and HR teams to determine which employee fields should sync to ContactMonkey. See Field Label Data Set Table for available options.

Step 3: Generate Your API Key

The API key authenticates the connection between your HRIS and ContactMonkey.

1. Click your name at the top right of your ContactMonkey dashboard
2. Click Settings
3. Click Integrations
4. Locate the List Management API tile and click Generate API Key
5. Copy and save the key immediately - you cannot view it again

Security Best Practices

• Store the API key in a secure password manager or vault
• Do not share the key via email or messaging apps
• Only provide the key to authorized IT/HRIS administrators
• Regenerate the key immediately if compromised

Step 4: Configure the API Connection

This section is for HRIS/IT administrators configuring the technical connection.

API Endpoint Information

Request URL by region:

https://contactmonkey.com/public_api/v1/lm_imports

https://contactmonkeyeu.com/public_api/v1/lm_imports

https://contactmonkey.au/public_api/v1/lm_imports

https://contactmonkey.ca/public_api/v1/lm_imports

Request specifications:

• Method: POST
• Authentication: Bearer Token (in Authorization header)
• Content-Type: multipart/form-data
• Schedule: 
  • Once every 24 hours for Replace Sync
  • Once every 2 hours for Upsert Sync

Authentication

Authorization header format:

Authorization: Bearer <your_api_key>

Replace <your_api_key> with the token from step 3. This is the only required header.

Request Parameters

The API requires two parameters:

1. Org_ID (required)

• Type: Integer
• Description: Your organization ID from Step 1
• Format: Numbers only (e.g., 12345)

2. Mode (optional)

• Type: Text
• Description: Controls the synchronization mode/behaviour. Set to upsert to enable the upsert mode where existing contacts and fields are not deleted. Omit the parameter or set it to replace to delete contacts and fields not provided in the CSV (overwrite).   
• Default: Replace (if not provided the API uses the Replace Mode) 

3. CSV (required)

• Type: File
• Description: CSV file containing employee data
• Max size: 50MB
• Encoding: UTF-8
• Format requirements:
  • First row must contain field headers
  • First column must be "Email"
  • There should be no duplicate email addresses
  • Date fields must use format: YYYY-MM-DD

CSV File Structure

Download a sample here.

Field Label Data Set Table

Use these exact field names (case-sensitive) as column headers:

✨ Phone numbers must be in E.164 format - learn more here.

⭐ Dates must follow this format: YYYY-MM-DD 

Custom fields: You can add any additional column headers not listed above. They will be created as custom fields in ContactMonkey.

Understanding Data Sets

What are Data Sets?
Fields marked as Data Set: Yes provide a drop-down selection when filtering, making it easier to create accurate lists.

Non-Data Set Fields
Fields marked as Data Set: No allow text entry with operators like "equals", "contains", "does not contain", etc.

Why does this matter?
When you create filtered lists, data set fields show all possible values in a dropdown, preventing typos and speeding up list creation.

Step 5: Set Up Automated Daily Sync

Schedule an HTTP POST request to run once every 24 hours (Replace Sync) or once every 2 hours (Upsert Sync). 

Implementation Methods

For Advanced HRIS Systems: Use your HRIS system's built-in API automation tools to schedule the daily POST request.

For Basic HRIS Systems, choose one:

Option 1: Scheduled script (cron job)

• Save CSV export from HRIS to a server location
• Create a script that runs the cURL command
• Schedule the script to run daily (e.g., 2 AM local time)

Option 2: Cloud-based automation

• Use AWS Lambda, Azure Functions, or Google Cloud Functions
• Trigger daily via cloud scheduler
• Execute API call with Python, JavaScript, or other languages

Option 3: Integration platform

• Use Zapier, Make, or enterprise iPaaS solutions
• Create an automated workflow to export and POST data

Sample cURL Command

Replace placeholders with your actual values.

Replace Mode:

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

or

curl -v -X POST 'https://contactmonkey.com/public_api/v1/lm_imports' \
  -H "Authorization: Bearer <your_api_key>" \
  -F org_id=12345 \
  -F mode=replace \
  -F "csv=@/path/to/your/employee_data.csv"

Upsert Mode:

curl -v -X POST 'https://contactmonkey.com/public_api/v1/lm_imports' \
  -H "Authorization: Bearer <your_api_key>" \
  -F org_id=12345 \
  -F mode=upsert \
  -F "csv=@/path/to/your/employee_data.csv"

Important:

• Include @ symbol before the file path
• Ensure CSV is saved in UTF-8 encoding
• Verify the file path is correct and accessible

Example Implementation Process

1. HRIS exports CSV to local server location
2. Script sanitizes data (removes sensitive fields not needed in ContactMonkey)
3. Cron job runs daily at scheduled time
4. Script executes cURL command to POST CSV
5. ContactMonkey processes file and updates directory

Step 6: Test Your Configuration

Before scheduling automated runs, test your connection manually.

Testing Steps

1. Export a small CSV file from your HRIS (5-10 contacts)
2. Run the cURL command manually
3. Check for success response code (see below)
4. Log in to ContactMonkey and verify that contacts appear
5. Check that all expected fields are visible and populated

Success Response Codes

• HTTP 201 Created: First-time import, processed immediately
• HTTP 202 Accepted: Subsequent import, will process overnight

If you receive these codes, your configuration is correct.

Step 7: Verify the Integration

After your IT team completes setup and the first sync runs:

1. Click Directory at the top of your ContactMonkey dashboard
2. Verify contacts appear with the expected data fields
3. Check that all planned fields are visible and populated
4. Test creating a dynamic list using your synced fields

First sync timing:

• 201 response: Processes immediately (5-10 minutes)
• 202 response: Processes overnight

What Happens After Setup

Nightly syncs: Your HRIS data syncs to ContactMonkey automatically every 24 hours (Replace Sync) or every 2 hours (Upsert Sync)

Contact updates:

• New employees are added
• Departing employees are removed
• Information is updated

Field changes: Adding or removing columns in your HRIS export will add or remove fields for all contacts in ContactMonkey.

Best Practices

1. Test with a subset: Start with 10-20 contacts before syncing your full directory
2. Document your setup: Keep records of field mappings and automation configuration
3. Monitor regularly: Check sync logs and contact data weekly for the first month
4. Set up alerts: Configure notifications if your scheduled job fails
5. Keep backups: Save CSV templates and configuration details
6. Plan changes carefully: Communicate field additions/removals to your team before implementing
7. Review quarterly: Audit your field usage and remove unused fields

Troubleshooting

Click here for detailed error code explanations and solutions.

Quick reference:

• 403 Forbidden: API key doesn't match organization ID
• 404 Not Found: Incorrect organization ID or wrong regional endpoint
• 422 Unprocessable: Missing parameters or invalid CSV format
• 500 Server Error: File path format issue or CSV encoding problem

See Also

• List Management - Creating and Filtering Custom Contact Lists
• List Management - Sending Emails to a ContactMonkey Contact List
• List Management - Updating a Contact in Your ContactMonkey Directory