Who can use this feature?
Available on:
All Culture Amp subscriptions that have an active subscription with Humaans.
You can import employee data directly from Humaans into Culture Amp using a secure, one-way API connection. This ensures your employee list and demographics are always up-to-date.
Data Flow: Employee Data flows from Humaans into Culture Amp (one-way sync). Changes made in Culture Amp will not sync back to your HRIS.
Initial Setup Timeframe: Please note that due to the complexity and customization of Humaans, the full setup and validation process can take anywhere from a few days to several weeks. Please allocate sufficient time and internal resources for mapping and validation.
Choosing Your Integration Method
We offer two primary ways to connect your employee data. For Humaans, the API integration is the standard, recommended approach. The table below briefly outlines both options to help with decision-making:
Method | Type of Import | Best For | Key Difference |
Full Integration (API) | Full Employee Import | Organizations seeking real-time, daily automation of all employee data that the API supports. | Data transfer is handled automatically via a secure API connection. Users with an End Date in the HRIS become former employees instantly upon sync. If a user is simply removed from the sync report without an End Date, they will remain "Active" in Culture Amp until a manual sync is performed by our Culture Amp Support team. Properly terminating employees in your HRIS with an End Date is the only way to guarantee automatic deactivation. |
Partial Employee Import | Organizations that need complete control over file creation, have unique filtering requirements, or need to manage data fields not supported by the API. | You generate a file and securely transfer it to us at scheduled intervals. Users missing from the file are ignored unless you include an |
API Integration Checklist
Access Requirements & Terminology — Prerequisites and system logic.
Step 1: Connect & Authenticate — Locating and entering your API credentials.
Step 2: Field Mapping — Aligning your Humaans demographics with Culture Amp.
Step 3: Activate Integration — Establishing the technical connection.
Step 4: Run Your First Sync — Reviewing and importing employee records.
Troubleshooting & FAQs — Solving errors, duplicates, and sync blocks.
Before You Start: Access Requirements & Terminology
To set up the connection, you’ll need:
Access to your Humaans instance with the required role (see Permissions below).
Access to Culture Amp with Account Administrator or Employee data administrator permissions.
Important Considerations & Data Limitations
Important Considerations & Data Limitations
Humaans does not support the ability to exclude users via an exclusion field. If you need to exclude users from your sync, refer to the Exclude Employees (Optional) section in this article to see a workaround.
Terminology Breakdown
Terminology Breakdown
Term | Also Known As | Definition & Example |
Member | Employee / Person | Humaans refers to employees as "Members." The Member Profile is the central source for all personal and job data. |
Reports To | Manager / Supervisor | The field assigning a hierarchy. Located on the member's profile sidebar in the Humaans UI |
Employment Start/End Date | Start/Termination Date | Humaans labels these as "Employment" dates. Found under the Employment tab. |
Access Token | API Key / Bearer Token | The unique credential generated in Humaans to allow Culture Amp to read your data. |
Required Permissions & Rationales (Technical)
Required Permissions & Rationales (Technical)
Permission/Role | Permissions Needed in Humaans | Rationale |
Administrator | Access to | Only Administrators can generate tokens. The token's visibility is limited by the creator's access. |
Token Scopes | "View public data" | Required at a minimum to retrieve basic identity (names and emails). |
Token Scopes | "View public and private data" | Critical: This scope is required for sensitive demographics like Date of Birth and Employment End Date. Without this, terminations will not sync. |
Step 1: Connect & Authenticate Your Humaans Account
Sign in to Culture Amp with an account that has Account Administrator access.
Navigate to your Settings > Account > Integrations page in the Culture Amp platform.
Select Humaans from the list of integrations and click Continue setup
Click I am an admin to confirm your Humaans Admin permissions
You will see the request to read your Humaans employee data. Click Next
You will be prompted to insert your API key from your Humaans account. If you require more detailed steps with screenshots, please follow the guide supplied here. Once pasted, click Next.
🔑 Accessing your Humaans API Access Token
🔑 Accessing your Humaans API Access Token
To authenticate Humaans.io, you will need to generate an API Key and paste it into the linking flow.
Note: The steps below are sourced from Merge, our integration partner. We recommend checking their official guide for the most current instructions: Merge Humaans Account Linking Guide
Prerequisites:
Please ensure you have Admin permissions in your company's Humaans.io instance or someone has shared their access with you.
Instructions:
Step 1: Generate your API key
Log into the platform
From the sidebar, click Settings (or the three dots/organization name) and select API access tokens
3. Create or edit an existing API Key
If you have an existing API key, you can use the edit button to update the scopes on the key
If you do not have an existing key, use the "Generate new token" button to create a new key:
4. Configure the scopes you will need for your integration
At a minimum, you will need "View public data" to retrieve basic employee data like name, email, and job title
"View public and private data" is required to pull pre-hires to detect off-boarded employees. Without this scope, employees will not be picked up until their date of hire and employees will not be identified as terminated.
Enabling "View public and private data" allows us to read information including:
gender
date of birth
country
city
state
zip_code
remote_id
job_title
phone_number
email_address
data for new hires and offboarded employees
If you need compensation data for your integration, enable "View compensations"
You can reference the Humaans docs for more details on API key scopes
Step 2: Paste your API key into the linking flow
Step 2: Setting Up Demographic Field Mapping
Once you have authenticated with Humaans, you will be prompted to map the demographic fields you would like to import into Culture Amp.
Core Demographics: Automatic Mapping
Core Demographics: Automatic Mapping
The table below outlines the standard "out-of-the-box" configuration for Humaans. While Humaans is designed for simplicity, it remains a customizable platform; therefore, while we list the most common UI labels, your specific environment may have been modified by your Humaans administrator to use different naming conventions.
This information is intended for your technical Humaans administrator to help ensure the API user has the required permissions and visibility for the data objects needed for the connection.
Note:
Do not manually map the fields below unless instructed by a specialist.
The "Typical Humaans UI Label" represents the default Humaans naming. Your systems administrator may have customized these labels (e.g., renaming "Employee ID" to "Staff ID")
If the data for these core fields is not pulling correctly, reply with "Ask a Person" in a Support Conversation for a back-end custom mapping solution.
Typical Humaans UI Label | Primary Humaans API Endpoint (Data Location) | Culture Amp Field (The Destination) |
Work Email |
| Email (Unique Identifier) |
Employee ID |
| Employee ID (Unique Identifier) |
Full Name |
| Name |
Preferred Name |
| Preferred Name |
Date of Birth |
| Date of Birth |
Employment Start Date |
| Start Date |
Employment End Date |
| End Date |
Reports To (Work Email of referenced Manager) |
| Manager Email (Hierarchy demographic) |
Custom Demographics: Manual Mapping
Custom Demographics: Manual Mapping
If you track additional employee data in Humaans that you want to use as demographics in Culture Amp, follow these steps to set up custom mapping.
Step 1. Map Fields
Now that the initial authentication is complete, on your Integrations page, click Map fields.
Step 2. Select the Data Model
Select the data model for your target field (e.g., Employee).
Step 3. Set Details for the Target Field
Set the details for the field you are targeting in Culture Amp (the demographic name, e.g., Date of Birth).
Step 4. Choose the Matching Field from Humaans
Select the matching Humaans field that contains the data and click Save
Step 5. Save Mappings
You can Save mappings or click the + Field mapping icon to add more.
Alternatively, if you’re not ready to map fields yet, you can click Skip for now and return to mapping later.
Tip: If you are unsure of the correct Humaans field, please involve your technical Humaans administrator to locate the correct API name.
Note: Some HRIS APIs may limit access to specific custom fields. If you cannot find a required demographic field during mapping, you may need to:
Map an alternate custom field that contains similar data.
Manage the demographic outside of Humaans directly in Culture Amp via manual imports or SFTP.
Exclude Employees (Optional)
Exclude Employees (Optional)
Humaans does not support an exclusion field via the API. If you need to exclude users from your sync, you must use Culture Amp’s bulk deactivation feature as a workaround.
Allow the initial sync to import all users from Humaans, including those you want to exclude.
In Culture Amp, export a copy of your user list:
Go to Settings > Employee Data > Users > Import & Export > Export
Check the box for Include deactivated users
The export will contain a column labeled Employee Deactivated.
Update the
Employee Deactivatedcolumn in the exported file:Assign
"TRUE"to all users you want to exclude (they will be deactivated).Assign
"FALSE"to users who should remain active.
Save the file and perform a manual partial import:
Go to Settings > Employee Data > Users > Import & Export > Import users > Upload your file > Partial import.
Once complete, deactivated users will remain deactivated and will not be reactivated in future syncs.
Step 3: Activate Integration
After mapping your fields, click Sync, and the system will run an initial sync to connect your Humaans account details and mappings.
Note: This sync does not import employee data yet.
You will see a "Syncing data" message. This initial sync can take up to 12 hours to complete, depending on the size and complexity of your Humaans configuration.
Feel free to navigate away from the page. The process runs in the background.
The "Syncing data" message confirms the connection and mapping setup. Once this first sync completes, you can proceed to import your employee data through another sync.
Note: As part of our commitment to data security, only data relevant to your import and field mappings will be stored.
Step 4: Run your First Employee Data Sync
Once the initial setup sync is complete, the Integrations page in Culture Amp will update. Follow these steps to run your first employee data import:
Click the Finalise sync button.
Click Get Started.
On the review page, ensure Sync is selected in the "Sync with merge" section (ignore the other options).
Culture Amp will validate the data. If there are no concerns, click Next.
Review the data: Carefully examine the review screen, which shows the number of new employees to be created, existing employees to be updated, and employees to be deactivated.
If the data looks correct, click Import Data to pull the employees into Culture Amp.
After the import is complete, click Go to Users to review the new users.
Important: If you see any unexpected numbers (e.g., too many employees being deactivated or created), do not proceed with the import. Check the Troubleshooting section or reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.
Once these steps are completed, you will see the "Syncing data" notification appear on the Integrations page.
After syncing is complete, you will see the latest sync information, including the date and time, and confirmation that your Humaans integration is Connected.
Set Up Automated Daily Syncs
Set Up Automated Daily Syncs
By default, auto-syncs are Off. We recommend enabling daily syncing to ensure your employee demographics are kept up-to-date.
To enable: Go to Integrations, click on the Off button and toggle Auto-sync On.
To disable: Go to Integrations, click on the On button, then click Turn off auto sync.
Note: Auto-sync won’t run if the Finalise sync step is still displayed. Click Finalise sync to finish setup.
Troubleshooting/FAQs
If the fixes below don't resolve your issue, please remember that the high potential for customization in Humaans means complex mapping or sync problems often require a specialist. Please reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.
General Data Integrity & Import Management
The first step when investigating any data issue is to check the Import Summary Screen for your most recent import.
Go to Settings > Employee Data > Import History.
Select your most recent import to view details.
This screen provides information on the state of your integration, any specific errors, or will prompt you to run a manual sync to identify problems.
Humaans: Integration-Specific Errors
Humaans: Integration-Specific Errors
Issue | Cause | Suggested Fix |
Demographics (e.g., Date of Birth) are not syncing | The Humaans API Access Token was created with the "View public data" scope only. | Action: In Humaans, edit your API token or generate a new one ensuring "View public and private data" is selected. Personal demographics are considered "private" data in Humaans. |
Need to Edit/Delete Mappings | Mappings are locked in the Culture Amp platform once set up. Adding or editing custom mappings often requires a full back-end sync to be triggered by our Culture Amp support team for the changes to be reflected in the platform. | Contact Culture Amp Support:
|
Manager / Hierarchy is missing for some users | The person listed in the "Reports To" field in Humaans does not have a Work Email address on their own profile. | Action: Check the Manager's profile in Humaans. The integration requires the Manager to have an email address to successfully link direct reports in Culture Amp. |
Terminations not processing automatically | The API token lacks the "View public and private data" scope, preventing the sync from seeing "Offboarded" status. | Action: Update your Humaans token scopes. Without the "Private" scope, Humaans hides the offboarding/termination details from the API. |
Unable to Exclude Specific Employees | Humaans does not support a native "Exclusion" toggle or custom exclusion field that is readable via the API. | Workaround: You must use Culture Amp's Bulk Deactivation option. See the Exclude Employees (Optional) section above for full steps. |
Switching from CSV or Other Imports
Switching from CSV or Other Imports
If you are moving from CSV uploads or a different integration, keep the following in mind:
Demographic Consistency: When mapping fields, you must map the data to the exact same demographic field you used historically (e.g., mapping to "TEAM" is different from mapping to "TEAM NAME"). Using an incorrect or slightly different title risks discontinuity in your trended survey results.
Recommended Action: To avoid confusion, we recommend navigating to Settings > Employee Data Demographics and deleting the old, unused demographics after your first successful sync. (This won't impact any previous survey results.)
Handling Duplicate Employees
Handling Duplicate Employees
Culture Amp uses two fields as unique identifiers for user profiles: Email and Employee ID.
As long as at least one of these remains consistent between Humaans and Culture Amp, the sync will successfully update the existing profile rather than creating a new one.
Duplicate Risk: If you change both the Email and the Employee ID simultaneously in Humaans, the sync will not find a match and will create a duplicate profile.
If you see a duplicate profile error flag during your import, take the following steps:
Scenario | Action to Take |
A. Before Changes Are Applied | During the first sync review screen, stop the sync. Update the employee emails in Culture Amp to match those in Humaans.
|
B. After Changes Are Applied | To clean up the duplicated profiles:
|
Further Guidance | Check out our dedicated support guide for further information on duplicate employee clean-up. |
Sync Blocked to Protect Employee Privacy
Sync Blocked to Protect Employee Privacy
Your automated daily sync might be blocked if Culture Amp detects a high-risk change for an employee. You will receive an email notification if this occurs.
When It Happens: The sync is blocked if a combination of an employee's Name, Date of Birth, or Email is changed simultaneously.
Purpose: This prevents one employee from accidentally getting access to another employee's private information (like performance reviews).
Fix: If you've intentionally changed the employee's details, you can run a manual sync to push the change through. Go to Settings > Employee Data > Users, click Import data, and select Sync. Culture Amp will guide you through the rest.
Redaction of Sensitive Data
Redaction of Sensitive Data
As part of this integration, Culture Amp has the ability to redact sensitive data at your request. If you need any fields to be disabled/redacted for your account, please reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.
💬 Need help? Just reply with "Ask a Person" in a support conversation to speak with a Product Support Specialist.