List Management - Troubleshooting HRIS API Integration

This guide helps you diagnose and fix common issues with HRIS API integration.

Success Response Codes

These codes indicate your API call worked correctly:

HTTP 201 Created

What it means: This is your organization's first API import
What happens: The import runs immediately
Action needed: None - verify contacts appear in ContactMonkey

HTTP 202 Accepted

What it means: This is a subsequent import for your organization
What happens: The import will run overnight during the scheduled sync
Action needed: None - check contacts the next day

Error Response Codes

HTTP 403 Forbidden

What it means: Authentication failed

Common causes:

• API key doesn't match the organization ID
• Incorrect or expired API key
• API key belongs to a different organization

How to fix:

1. Verify you're using the correct organization ID (numbers only)
2. Confirm the API key is current and hasn't been regenerated
3. Check that org_id and the API key are from the same ContactMonkey account
4. Regenerate API key if necessary (in Settings → Integrations → List Management API)

Note: This error returns no response body

HTTP 404 Not Found

What it means: Organization not found

Response:

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

Common causes:

• Incorrect organization ID
• Using the wrong regional endpoint
• Organization ID doesn't exist in ContactMonkey

How to fix:

1. Double-check your organization ID with your ContactMonkey administrator
2. Verify you're using the correct regional endpoint:
   • US: https://contactmonkey.com/public_api/v1/lm_imports
   • EU: https://contactmonkeyeu.com/public_api/v1/lm_imports
   • AU: https://contactmonkey.au/public_api/v1/lm_imports
   • CA: https://contactmonkey.ca/public_api/v1/lm_imports
3. Contact your Customer Success Manager or the Technical Support team to confirm your organization ID

HTTP 422 Unprocessable Entity

What it means: Request is missing required information or the data is invalid

This error has several possible causes:

Missing org_id Parameter

Response:

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

How to fix:

• Add the org_id parameter to your request body
• Ensure it's formatted as -F org_id=12345 (numbers only)

Missing Bearer Token

Response:

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

How to fix:

• Add authorization header: Authorization: Bearer <your_api_key>
• Ensure "Bearer" is included before the token
• Check for typos in the header format

Missing CSV File

Response:

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

How to fix:

• Add the CSV file parameter: -F "csv=@/path/to/file.csv"
• Ensure @ symbol is before the file path
• Verify the file path is correct and accessible

Invalid CSV Format

Response:

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

Common causes:

• CSV is not UTF-8 encoded
• Email column is missing
• Email column is not the first column
• CSV has formatting issues (mismatched quotes, incorrect delimiters)
• The file is corrupted

How to fix:

1. Verify Email is the first column in your CSV
2. Save CSV in UTF-8 encoding (not UTF-8 with BOM)
3. Check for proper CSV formatting:
   • Commas as delimiters
   • Quotes around text with commas
   • No extra spaces in headers
4. Test with a simple 2-3 row CSV first
5. Use a CSV validator tool to check formatting

HTTP 500 Internal Server Error

What it means: Server-side error or request format issue

Common causes:

• Incorrect CSV file path format (missing @ symbol)
• CSV not saved in UTF-8 format
• File size exceeds 50MB limit
• Special characters not properly escaped
• Server-side processing issue

How to fix:

1. Verify file path format: -F "csv=@/path/to/file.csv"
2. Ensure @ symbol is present before the path
3. Confirm CSV is saved as UTF-8 (not UTF-8 with BOM)
4. Check the file size is under 50MB
5. Test with a smaller CSV to isolate the issue
6. If the problem persists, contact ContactMonkey support with:
   • The exact cURL command you're using (remove API key)
   • Sample of CSV headers
   • Error response received

Common Issues and Solutions

Contacts Not Appearing After Sync

Possible causes:

• First sync (201 response) hasn't been processed yet
• Subsequent sync (202 response) scheduled for overnight
• CSV file is empty or malformed
• Email addresses are invalid

How to fix:

1. Wait 5-10 minutes after first sync (201)
2. Wait until the next day after the subsequent sync (202)
3. Verify CSV has data rows (not just headers)
4. Check that email addresses are properly formatted

Some Fields Not Syncing

Possible causes:

• Field names don't match exactly (case-sensitive)
• Field names have typos
• CSV columns are empty for all rows

How to fix:

1. Compare your CSV headers to this table
2. Ensure exact capitalization (e.g., firstName not firstname)
3. Verify data exists in CSV columns
4. Check for hidden characters or spaces in headers

Contacts Were Deleted Unexpectedly

Possible causes:

• Contacts were not included in the latest CSV
• HRIS export filtered out certain employees
• CSV export process has errors

How to fix:

1. Review your HRIS export settings - ensure all employees are included
2. Check CSV contains all expected email addresses
3. Verify the export process didn't fail partway through
4. Re-run sync with the complete CSV to restore contacts

Manual Changes Keep Getting Overwritten

This is expected behavior.

The HRIS API sync completely overwrites ContactMonkey data. Any changes made directly in ContactMonkey will be lost after the next sync.

Solution: Make all changes in your HRIS system, not in ContactMonkey.

Testing Your Connection

Using cURL to Test

Run a manual test before scheduling automated syncs:

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/test.csv"

Create a test CSV with 2-3 contacts:

Email,firstName,lastName,department
test1@company.com,John,Smith,Engineering
test2@company.com,Jane,Doe,Marketing

Verification Checklist

After running a test:

• Response code is 201 or 202
• No error messages in response
• Test contacts appear in ContactMonkey (wait time depends on response code)
• All CSV columns appear as fields in ContactMonkey
• Data is accurate for each contact

See Also

• List Management - Setting Up HRIS API to Sync Employee Contacts