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 Perceptyx Generic SFTP HRIS Template, which you can get from your Perceptyx team. Read through its Read Me First and Field Reference 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. 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. |
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 sso_id employee_language | Optional | Text | Only include sso_id if the identifier your single sign-on uses isn't the work email or employee ID. |
| 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 your own 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.
- Once you've added an optional column, keep its header in the file. If you don't have a value for someone, leave the cell blank rather than deleting the column.
- Leave out fields Perceptyx doesn't use, like national ID numbers, usernames, or profile pictures.
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