How to Prepare, Transfer, and Manage Employee Data via SFTP

Using SFTP with Recognize allows your organization to securely and automatically sync your employee roster. Your HR or internal system sends a file to Recognize—typically on an automated schedule—and Recognize uses that file to:

• Create new employee accounts

• Update existing accounts

• Disable accounts for employees no longer present in your file

Because of this, the file serves as the source of truth for your employee data within Recognize.

Jump to: Error Code Descriptions and Resolutions

1. Requirements for SFTP Integration

To begin syncing data via SFTP, you will need the following:

✔ 1. Your Employee File (CSV or Excel)

Your file must follow the Recognize import template:
Download Template Here

✔ 2. SSH Public/Private Key Pair (OpenSSH Format)

Generate a key pair using:
https://www.ssh.com/ssh/keygen/
(Do not send your private key to Recognize.)

More about key pairs

✔ 3. An SFTP Client

Your client must support public/private key authentication.

✔ 4. Outbound Internet Access on Port 22

Ensure your firewall allows outbound connections to port 22.

✔ 5. A Static Public IP Address

Your SFTP connections must originate from a fixed IP so Recognize can allow-list it.

2. Setting Up Your SFTP Connection

Follow the steps below to establish your connection with Recognize.

Step 1: Generate Your SSH Key Pair

If you do not already have a public/private key:

1. Create a new key pair using these instructions:
   https://www.ssh.com/ssh/keygen/

2. Keep your private key secure.

3. Only the public key will be shared with Recognize.

    

Step 2: Send Required Information to Recognize

Email the following to support@recognizeapp.com:

1. Your public SSH key
   (Do not send your private key.)

2. Your organization’s static public IP address
   This is the IP your SFTP server will use to connect.

3. Email addresses of users who should receive upload reports

   • These must be users with existing Recognize accounts.

   • To create a service account not included in your SFTP file:

     • Manually create the account in Recognize

     • Make it a Company Admin
       (Prevents it from being disabled by the SFTP file)

        

Step 3: Recognize Creates Your Dedicated Connection

Within 2 business days, Recognize will:

• Create your dedicated SFTP connection

• Allow-list your IP address

• Provide your SFTP username and connection details

You may then begin sending files.

3. SFTP Connection Details

Use the following settings when configuring your SFTP client:

• Host: sftp.recognizeapp.com

• Port: 22

• Username: Provided after setup

• Upload Path: /uploads

Step-by-step client configuration instructions

4. File Requirements & Formatting Rules

To ensure your file processes correctly, follow these formatting rules.

Required Fields

If an email is present

These fields are required:

• Email

• First Name

• Last Name

If an email is NOT present

A phone number becomes required.
Phone-only accounts are allowed only if:

• You are on the Enterprise Plan, and

• You have enabled phone-only accounts in your admin settings.

Employee ID (Optional but Recommended)

Employee ID serves as the most stable account identifier.

5. How Recognize Matches Your Records

Recognize identifies each employee using the first available identifier from this list:

1. Employee ID (recommended)

2. Email

3. Phone number

Important:

If an employee’s identifier changes (e.g., employee ID updated), Recognize will treat them as a new employee unless the identifier is updated inside of Recognize before your next file runs. To update an Employee ID - contact support@recognizeapp.com

6. Standard vs. Custom Fields

Standard Fields

All columns included in the Recognize template are fully supported.

Custom Fields (Enterprise Only)

• Enterprise customers may add up to 10 custom fields.

• Submit requests to: support@recognizeapp.com

Any field not in the standard template is considered a custom field.

7. Source of Truth Behavior

Your SFTP file overwrites existing values in Recognize.

This means:

• You cannot manage fields both manually and via SFTP.

• Attributes like Team and Role will always be overwritten if they appear in your file.

If you want manual control:

Do not include those fields in your SFTP file.

Instead, use:

• Dynamic Teams

• Dynamic Roles

These features allow team and role assignments to sync from another field (standard or custom), while still allowing manual control inside Recognize.

8. Remove Unused Columns

If a column is not being used:

• Delete it entirely from your file.

Leaving unused columns blank will overwrite values in Recognize with empty data.

9. Multi-Value Fields

Only Team and Role support multiple values.

Format:

Engineering,Leadership

Use a comma to separate values.

10. Date Formats

To ensure correct processing:

Birthday

• Format: MM/DD
  (No year)

Start Date

• Format: MM/DD/YYYY

If you require a different date format, contact:
support@recognizeapp.com

11. Supported Locale Codes

If you include the Locale field, it must match one of Recognize’s supported codes:

ar, en-AU, fr-CA, da, de, es, fr, en-GB, it-IT, nl-NL,
no, pl, pt, sv-SE, en, mn, hi, th, zh-CN, zh-TW, ja

Invalid locale codes may be ignored.

12. Automated File Delivery

Most organizations configure their internal system to send their SFTP file automatically on a regular schedule (e.g., daily or weekly). Recognize processes the file as soon as it arrives.

13. What Happens After Your File Processes

Once Recognize processes your file:

• A detailed report is emailed to your designated recipients.

• This report tells you whether the upload was successful or if errors occurred.

• Errors are reported at the row level, so you can identify:

  • Exactly which records failed

  • The reason they failed

This gives you full visibility into the status of your sync.

14. Summary Checklist

Before submitting your file:

✔ Follow the Recognize template
✔ Include required fields
✔ Keep identifiers consistent
✔ Delete unused columns
✔ Follow date format rules
✔ Use commas only for multi-value fields (Team/Role)
✔ Use supported locale codes
✔ Verify your SSH key, IP address, and SFTP client setup
✔ Ensure your notification recipients have Recognize accounts

Error Code Descriptions and Resolutions

Select the error code from the below list that you'd like to learn more about to jump to the relevant information.

• Email has already been taken. If this is you, you may reset your password <a href='https://recognizeapp.com/password_resets'>here.</a>
• Employee ID cannot be modified once set
• Mysql2::Error: Duplicate entry 'User@domain.com-domain2.com' for key 'index_users_on_unique_key’
• Start date invalid/birthday invalid
• Phone already taken
• Formatting issue
• Locale ‘example’ is not one of the supported locales
• Manager email not found

'Email has already been taken. If this is you, you may reset your password <a href='https://recognizeapp.com/password_resets'here.</a>'

Issue Reason: This error occurs when the Employee ID listed on the spreadsheet does not match the Employee ID that we have listed with the same email in Recognize. Employee IDs and Email Addresses can only exist once on a Company account. Because Employee ID’s are the main account identifier, when a new Employee ID is included in an import, the system thinks that a new account is being created, but because the email address already exists and is paired with a different Employee ID, we encounter an error.

Example: In the client’s sFTP spreadsheet, the Employee ID listed with the email address John.Smith@Recognizeapp.com is CF456. However, The email address John.Smith@Recognizeapp.com is already present on the company’s account with the Employee ID AB123.

The Solution: The Employee ID needs to be cleared by Recognize Engineering so it can be updated in your next user sync.

Please contact Support@recognizeapp.com for help with this and include the following details:

1. Ask to please Merge Johnathen.Smith.2@Recognizeapp.com → John.Smith@Recognizeapp.com, specifying which profile to delete and which to keep active.
2. Confirm the correct Employee ID for the user

Note: The data in your spreadsheet must match the active account and correct Employee ID.


 

'Employee ID cannot be modified once set'

Issue Reason: This error appears when there is an attempt to add an Employee ID and an Email Address that were both found in our system, but not together. To elaborate, if an Employee ID and Email address are included in an import and those both already exist on two separate accounts, our system will assume that you are attempting to update the Employee ID.

Example: John Smith is listed in the import spreadsheet under the email address John.Smith@Recognizeapp.com and the Employee ID AB123. In Recognize, there are two accounts that already exist for John: John.Smith@Recognizeapp.com is listed with the Employee ID CF456, and the Employee ID AB123 is listed next to John.Smith.2@Recognizeapp.com. Because both the Employee ID ‘AB123’ and Email Address ‘John.Smith@Recognizeapp.com’ both exist in Recognize but on two separate accounts, we get the error 'Employee ID can not be modified once set'.

The Solution: Because an Employee ID is the main identifier on a user’s profile, it cannot be updated via Spreadsheet Import until we first ask our Engineering Team to clear the old Employee ID. Then, the new Employee ID can be added to the user's profile in your next Spreadsheet Import (provided the email address did not also change, as that is the secondary identifier on an account). So in summary, the solution is to email Support@recognizeapp.com and request to clear the old Employee ID so that it can be replaced during the next user sync.

'Mysql2::Error: Duplicate entry 'User@domain.com-domain2.com' for key 'index_users_on_unique_key’'

Issue Reason: This error appears when an account was previously soft-deleted by our Engineering Team (usually during an account merge), and while no longer visible on the front end, that account still exists in our back end, and so cannot be updated via Spreadsheet Import until it has been archived.

Example: John Smith is listed in the import spreadsheet under the email address John.Smith@Recognizeapp.com. Let's say our Engineering Team was instructed to merge John.Smith@Recognizeapp.com with Johnathan.Smith@Recognizeapp.com and leave the active account under Johnathan.Smith@Recognizeapp.com. Upon completing this request, they will have soft-deleted the email address John.Smith@Recognizeapp.com. When an import is attempted with the previously soft-deleted email address John.Smith@Recognizeapp.comattached to a new user, our system will see it as a duplicate entry and will return the above error.

The Solution: If you cannot find the duplicate email or employee ID in your company's Recognize account, it is likely that the account was previously soft deleted by Recognize Engineering, and while not visible in the company account, it still exists in the back end. Please reach out to Support@recognizeapp.com to confirm if this is the case. If the Recognize Engineering Team confirms that this account has been soft-deleted, you can then give our team permission to archive the email address so that it can be updated in your next sync.


 

Start date invalid/birthday invalid

Issue Reason: This error appears when a date isn't in the correct format.

Example: John Smith has a birthday of May 25, and in the user file, the birthday is listed as 25 May.

The Solution: 

• Format date columns as strings and follow formats in sample spreadsheet
• Date formats, such as birthday should only be in 05/25 format
• Formatting must be consistent throughout the spreadsheet

Phone already taken

Issue Reason: The spreadsheet already contains a user with the same phone number.

Example: John Smith has a phone number of 555-5555, and Jane Doe is included in the user file with the same phone number of 555-5555.

The Solution:

Because phone number is a unique identifier, all phone numbers in the platform must be unique.

Formatting issue

Issue Reason: The spreadsheet contains data in an invalid format.

Example: John Smith is listed as 'Smith, John' in the spreadsheet.

The Solution: All formatting must follow our sample spreadsheet, with names not comma separated, and dates in string format.

Locale ‘example’ is not one of the supported locales

Issue Reason: The spreadsheet contains an unrecognized locale code in the 'Locale' column.

Example: John Smith has a locale of 'tx' in the user file.

The Solution:

'Locale' can ONLY be set as one of the following supported locales, and these locales are generally used to support languages in the platform:

'ar' or '(Arabic) العربية'

'en-AU' or 'Australian English'

'de' or 'Deutsch (German)'

'es' or 'Español (Spanish)'

'fr' or 'Français (French)'

'fr-CA' or 'French Canadian'

'en-GB' or 'Great Britain English'

'pt' or 'Português (Portuguese)'

'en' or 'United States English'

'mn' or 'ˈmɔ̙̃ɴɢɞ̜̆ɮ çe̝ɮ (Mongolian)'

'zh-CN' or '中国人 (Chinese Simplified)'

'zh-TW' or '中國人 (Chinese Taiwan)'

'ja' or '日本 (Japanese)'


 

Manager email not found

Issue Reason: If you're doing a "dry run" and the manager isn't already in the system, it'll return the manager error, even if the manager is in the upload you are currently dry-running. If you're not doing a dry run, and you get that manager error, it's because the manager isn't already in our system, and they're not in the current upload.