Platform setup
No connector for your HR system? Send Perceptyx one employee file on a schedule, and it takes care of the rest.
Use the Generic SFTP connector when your HR system isn't available as a native connector, or when your team would rather control the export itself. SFTP stands for secure file transfer protocol, a standard way to move files between systems safely.
Here's the idea. Your HR or technology team creates a single employee data file and sends it to Perceptyx on a recurring schedule. Perceptyx reads that file through the connector and uses it to set up users and power surveys, your reporting hierarchy, personalization, and reporting.
This article walks through
How it works
- Send the full file, every time. The connector reads the complete file on every transfer. If someone was in the last file but isn't in the next one, Perceptyx treats them as having left. So always include every employee who should be in Perceptyx, not just the people whose details changed.
- Daily is best. A scheduled daily transfer keeps your data current without anyone having to remember to do it.
- Records match on employee_id. Keep this value the same for as long as someone works for you.
- It's encrypted while it travels. Secure file transfer encrypts both the sign-in and the file itself. You can add another layer of encryption if you want to (see Optional file encryption).
Heads up
Because Perceptyx treats anyone missing from the file as someone who has left, a partial file can remove people you didn't mean to remove. Double-check that your export includes everyone in scope before you schedule it.
Prepare your file
Start from the Generic SFTP field mapping template. It's view-only, so download your own copy to work in. Then read through its Read Me First, Field Reference, and Enumerated Values tabs before you build your export.
File settings
| Setting | Requirement |
|---|---|
| File name | HRIS.csv exactly. The name is case-sensitive. |
| Format | A comma-separated values (CSV) file saved with UTF-8 text encoding. One row per employee, with the header row first. |
| Headers | The exact column names listed below, in lowercase with underscores (like_this). Headers are case-sensitive. |
| Dates | YYYY-MM-DD |
| True or false values | TRUE / FALSE |
| Country | The uppercase two-letter country code from the ISO 3166-1 alpha-2 standard, like US, GB, or NL. |
| Compression | None. Don't zip or password-protect the file. |
| Size | Up to 250 MB. Contact Perceptyx if you need more. |
Required columns
Five columns are required for every employee, and a sixth is required in some cases. Two of them identify the employee, and they're different on purpose.
| Column | What it holds | Example |
|---|---|---|
| employee_id | A permanent identifier your system generates, which never changes even if the person changes roles, names, or employee numbers. This is what Perceptyx uses to match records. | 7f9c2b14-8a3e-4d6f-bb21-0c5e9a17d4f2 |
| employee_number | The everyday employee number people recognize, like the one on a badge or payslip. | 00038108 |
| first_name | Legal first name. | |
| last_name | Legal last name. | |
| work_email | Work email address. This is the main identifier for setting up a user's access. | |
| sso_id | Your single sign-on identifier. Required only if it isn't the employee's work email or employee number. Used to sign employees in. |
Note
If your HR system doesn't have a permanent system-generated ID, put the employee_number value in both identifier columns.
manager_id always has to contain the manager's employee_id, so your reporting hierarchy connects up correctly.
Recommended and optional columns
| Column | Status | Type | Notes |
|---|---|---|---|
| manager_id | Recommended | Text | The manager's employee_id. Builds your reporting hierarchy. |
| display_full_name | Recommended | Text | Used for personalization and reporting in 360 feedback and other multirater surveys. |
| start_date | Recommended | Date | Survey eligibility and setting up users. |
| employment_status | Recommended | Text | ACTIVE / PENDING / INACTIVE |
| termination_date | Recommended | Date | Leave blank for active employees. |
| job_title | Recommended | Text | Survey personalization. |
| effective_date | Recommended | Date | The date the employee started their current position. |
| employment_type | Recommended | Text | FULL_TIME / PART_TIME / INTERN / CONTRACTOR / FREELANCE |
| flsa_status | Recommended | Text | Status under the United States Fair Labor Standards Act: EXEMPT / SALARIED_NONEXEMPT / NONEXEMPT / OWNER |
| work_country | Recommended | Text | The two-letter country code (ISO 3166-1 alpha-2). |
| personal_email | Optional | Text | Used for Lifecycle surveys. |
| mobile_phone_number | Optional | Text | Used for survey invitations by text message. International format works best: a plus sign, the country code, then the number, like +14155550123. This is known as the E.164 format. |
| gender ethnicity marital_status date_of_birth | Optional | Text or date | Used for demographic comparisons. The template lists the standard values. |
| termination_type voluntary_termination regrettable_termination | Optional | Text or true/false | The reason someone left, and whether it was voluntary or regrettable. |
| position_id employee_language | Optional | Text | position_id is the employment position ID. employee_language is the employee's language code, used to send invitations in different languages. |
| department division business_unit job_level job_function job_category | Optional | Text | For breaking down results by part of the organization. |
| company_display_name | Optional | Text | Company or legal entity name. |
| state city zip_code street_1 street_2 location_name location_type | Optional | Text | Work location. location_type is HOME / WORK. |
Adding or removing columns
Want to send something that isn't on this list? Add a column with a lowercase header that uses underscores, then let your Perceptyx team know so they can map it.
- If you don't have an optional field, or don't want to share it, you can delete that column so your file doesn't carry extra fields.
- Leave out fields Perceptyx doesn't use, like national ID numbers, usernames, or profile pictures.
Before you export
- Delete the Read Me First, Field Reference, and Enumerated Values tabs. The file you send should contain only the header row and your employee rows.
- Keep the header row exactly as it appears on the HRIS Template tab. Column names are case-sensitive.
- Save or export the file as a CSV (UTF-8) named HRIS.csv.
Deliver the file
Recurring transfer (recommended)
Set up your HR system or a file transfer tool to send HRIS.csv to the connector on a schedule. The connector linking flow shows you the values to enter in your file transfer tool:
| Setting | Value |
|---|---|
| Delivery method | SFTP |
| SFTP address | The address shown in the linking flow, starting with sftp:// |
| Directory | The directory shown in the linking flow |
| Authentication | An SSH key, which is a pair of matching keys used to sign in securely (SSH stands for Secure Shell). Generate the key pair in your system, then paste the public key into the linking flow. |
| User ID | The User ID shown in the linking flow |
| File name | HRIS.csv |
Once your transfer is scheduled, go back to the linking flow and click Finish. The connector checks the format of your first file, and then your data starts syncing on your schedule.
Manual upload (quick start)
Want to get going or test things right away? Upload HRIS.csv directly on the connector linking screen.
Optional file encryption
Secure file transfer already encrypts everything while it's moving. If you want the file encrypted while it's stored too, you can add Pretty Good Privacy (PGP) encryption on top. If you go that route:
- Get the connector's current public key from the linking flow or from your Perceptyx team.
- Encrypt HRIS.csv with that key in ASCII-armored format (a text-based version of the encrypted file), and send it with a .pgp extension.
- Don't sign the file unless you've been asked to. Signing can cause the file to fail when Perceptyx reads it.
Before this step
Not sure whether you need a file at all? Connect Your HR System to Perceptyx explains the pre-built connectors, which keep your data in sync without sending files.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article