Recognize Help Center

Recognize SFTP Integration Guide

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.

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)

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:

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, enter one of the 22 supported locale codes or accepted language labels below. Copy the value exactly as shown, including capitalization, hyphens, accents, and parentheses. Do not include quotation marks.

Use locale codes for a simpler import file. For the full reference, see Supported Languages & Locale Codes.

Supported locale values for spreadsheet imports
Language / Region Locale Code Accepted Language Label
Arabic ar (Arabic) العربية
Chinese (Simplified) zh-CN 中国人 (Chinese Simplified)
Chinese (Taiwan) zh-TW 中國人 (Chinese Taiwan)
Danish da Dansk (Danish)
Dutch nl-NL Nederlands (Dutch)
English (Australia) en-AU Australian English
English (Great Britain) en-GB Great Britain English
English (United States) en United States English
French fr Français (French)
French Canadian fr-CA Canadien français (French Canadian)
German de Deutsch (German)
Hindi hi हिन्दी (Hindi)
Italian it-IT Italiano (Italian)
Japanese ja 日本 (Japanese)
Mongolian mn ˈmɔ̙̃ɴɢɞ̜̆ɮ çe̝ɮ (Mongolian)
Norwegian no Norsk (Norwegian)
Polish pl Polski (Polish)
Portuguese pt Português (Portuguese)
Spanish es Español (Spanish)
Swedish sv-SE Svenska (Swedish)
Thai th ไทย (Thai)
Vietnamese vi Tiếng Việt (Vietnamese)

Invalid locale values may be ignored or reported as an import error. See the Locale error resolution below.

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

Find the error in your upload report below, then follow the fix steps. Account identifier errors require help from Recognize Support; formatting errors can usually be corrected in your file.

Email has already been taken

What it means
The email in your file already belongs to an account with a different Employee ID.

How to fix it

  1. Compare the employee’s email and Employee ID in your file with their existing Recognize account.
  2. Email support@recognizeapp.com with the correct Employee ID and ask for the old ID to be cleared by Engineering.
  3. If there are duplicate profiles, specify which profile to keep and which to merge or remove.
  4. Make sure your file matches the active account and correct Employee ID before the next sync.

Example
The file lists John.Smith@Recognizeapp.com with ID CF456, but the existing account uses ID AB123.

Back to error list

Employee ID cannot be modified once set

What it means
The email and Employee ID in your file already exist in Recognize, but on two different accounts.

How to fix it

  1. Email support@recognizeapp.com and request that Engineering clear the old Employee ID.
  2. Confirm the correct email and Employee ID pairing. Keep the email unchanged when adding the corrected ID in the next sync.

Example
The file pairs John.Smith@Recognizeapp.com with AB123. In Recognize, that email uses CF456, while AB123 belongs to John.Smith.2@Recognizeapp.com.

Back to error list

Duplicate entry error

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

What it means
A previously merged or soft-deleted account may still exist in Recognize’s back end, even though you cannot see it.

How to fix it

  1. Check whether the email or Employee ID already exists in your company account.
  2. If you cannot find it, email support@recognizeapp.com to confirm whether the account was soft-deleted.
  3. If confirmed, give the team permission to archive the old email address so it can be updated in the next sync.

Example
John.Smith@Recognizeapp.com was soft-deleted during a merge. Importing that email for a new user can trigger a duplicate entry error.

Back to error list

Start date invalid / birthday invalid

What it means
A date in your file does not match the required format.

How to fix it

  1. Format date values as strings, following the sample spreadsheet.
  2. Use MM/DD for birthdays, without a year, and MM/DD/YYYY for start dates.
  3. Keep the date format consistent throughout the file.

Example
For a May 25 birthday, enter 05/25 instead of 25 May.

Back to error list

Phone already taken

What it means
Two employees in your file share the same phone number. Phone numbers must be unique in Recognize.

How to fix it

  1. Find the duplicate phone number in your file.
  2. Correct the entries so each employee has their own unique phone number.

Example
John Smith and Jane Doe are both listed with 555-5555.

Back to error list

Formatting issue

What it means
One or more values do not follow the import template’s format.

How to fix it

  1. Compare the affected row with the sample spreadsheet.
  2. Put first and last names in their separate columns, rather than using a comma-separated name.
  3. Format dates as strings and use the required date formats.

Example
Enter John in First Name and Smith in Last Name, rather than Smith, John in one name field.

Back to error list

Unsupported Locale

Report message: Locale ‘example’ is not one of the supported locales

What it means
The Locale column contains an unrecognized value.

How to fix it

  1. Choose a code or accepted language label from Supported Locale Codes.
  2. Copy one value exactly, including capitalization, hyphens, accents, and parentheses. Do not include quotation marks.

Example
Use fr-CA or Canadien français (French Canadian) for French Canadian. Use vi or Tiếng Việt (Vietnamese) for Vietnamese. The value tx is not supported.

Back to error list

Manager email not found

What it means
Recognize could not find a manager account matching the manager email listed in the employee’s row. The email may not match the manager’s Recognize account, or the manager may not have an account yet. During a dry run, this error can also appear when the manager is included in the file but has not yet been added to Recognize.

How to fix it

  1. If the manager already has a Recognize account:
    Check the email associated with their account. Make sure the manager email in the employee’s row matches that email exactly, then correct the file if needed.
  2. If the manager does not have a Recognize account:
    Create an account for the manager, either by adding them to your user import or creating the account in Recognize. Use that account’s email as the manager email in the employee’s row so Recognize can link the employee to the correct manager.

If you are running a dry run

A dry run checks the file without creating accounts. If the manager is included in your file but does not yet exist in Recognize, this error may appear until you run the actual import.

  1. Go to Company Admin > Users.
  2. Select Import in the top right tertiary menu.
  3. Check Last Import > Dry run. True means the last upload was a dry run. Confirm that the manager is included in the file and that the manager email in the employee’s row matches their email in the file.
  4. Once the rest of the file is correct, uncheck the dry-run box and run the import to create the manager’s account and link the employee.

Back to error list