1. Overview
The SFTP (Secure File Transfer Protocol) integration enables customers to securely synchronize users and credentials with Genea using a CSV file.
Customers must provide a CSV file containing user and credential data. The file must follow the recommended structure and formatting rules outlined in this article to avoid processing failures or data conflicts.
2. SFTP Access & Authentication Requirements
Genea’s SFTP server uses public SSH key for authentication.
2.1 Access Setup
If you do not have SFTP credentials:
Generate an SSH key pair.
Share the public SSH key with the Genea Support team.
Genea will configure the SFTP server and provide:
SFTP Username
Host Endpoint
You must use your private key to connect to the SFTP server.
2.2 Connecting to Genea SFTP Server
Use the following command from your terminal:
sftp -i {{PRIVATE_KEY}} {{USER_NAME}}@{{GENEA_HOST}}Replace:
{{PRIVATE_KEY}}→ Path to your private key file{{USER_NAME}}→ Username provided by Genea{{GENEA_HOST}}→ Host endpoint provided by Genea
3. File Naming Convention
It is recommended to upload the CSV file to the Genea SFTP server using a timestamp-based naming convention. This ensures better traceability and easier identification of files.
Important:
Upload the file at the root level of the SFTP server.
Do not upload the file inside any folder.
You may follow any timestamp format that suits your internal process.
Example:
users_202602230502.csv
4. File Encoding Requirements
Ensure the file meets the following requirements:
UTF-8 encoding (recommended)
Standard comma-separated (.csv) format
No hidden characters
Additional columns beyond defined headers will be ignored and not be considered in sync.
Headers must match exactly (case-sensitive)
5. CSV File Structure
The CSV must follow the exact header names defined below.
⚠️ Headers are case-sensitive and must match exactly.
You can perform the following actions via SFTP sync:
Provision or deprovision users (Create / Update / Delete)
Sync the user’s profile picture
Manage memberships (Assign or remove user groups for a specific user)
Sync credentials (Create / Update / Inactivate / Delete physical cards)
Sync PINs (Create / Update / Delete)
Sync custom attributes (Update any custom attribute for users)
5.1 User Fields
CSV Header | Required/Optional | Valid Value | Description |
external_id | Required | Value that is unique for the user. | Unique identifier used to represent each user.
Genea will update the data based on this identifier. |
full_name | Required |
| The user's complete name, including First Name, Middle Name (if applicable), and Last Name.
This name will be displayed in the Genea system as the user's full name. |
Optional | Must be a valid email | If provided, the email must be valid and unique for each user. | |
user_status | Required | ACTIVE SUSPEND DELETE |
|
department | Optional |
| Department of the user |
employee_number | Optional |
| Employee Number of the user |
cost_center | Optional |
| Cost Center of the user |
mobile | Optional |
| Mobile Number of the user |
avatar_hex | Optional | Must be a valid hex string | Only fill in this column if the user’s avatar has changed. Otherwise, the system will overwrite the avatar each time the CSV file is processed. File size should be less than 5 MB.
Only JPEG, JPG and PNG will be supported.
Hex must contain valid Image Magic Bytes. Magic Bytes for JPEG: 0xFF / 0xD8 Magic Bytes for PNG: 0x89 / 0x50 / 0x4E / 0x47 |
avatar_url | Optional | Must be a valid url containing JPEG, JPG or PNG Image | Only fill in this column if the user’s avatar has changed. Otherwise, the system will overwrite the avatar each time the CSV file is processed.
File size should be less than 5 MB.
Only JPEG, JPG and PNG will be supported. |
Custom Attributes | Optional |
| How to Find the Custom Attribute Column Name for Your CSV Upload? 1. Log in to the Genea dashboard and navigate to User Management > Attributes. 2. Select the Custom Attribute tab. 3. Click the Connect link. A popup will appear. 4. In the popup, switch to the SFTP tab to view the External Name, which is the column name you should use in your CSV file.
What should be the correct value format for each custom attribute type in the CSV?
TEXT: Populate a string value DROPDOWN: Populate a string value CHECKBOX: For multiple selections, populate values separated by a double pipe (||) DATEPICKER: Populate the date in MM/DD/YYYY format BOOLEAN: Populate either Yes or No |
5.2 User Group Fields
CSV Header | Required / Optional | Valid Value | Description |
assign_user_groups | Optional | User group must exist in Genea | Provide the user group names, separated by a double pipe (
If no user group names are provided, this field will be ignored. |
remove_user_groups | Optional | User group must exist in Genea | Provide the user group names, separated by a double pipe (
If no user group names are provided, this field will be ignored.` |
5.3 Card Fields
CSV Header | Required / Optional | Valid Value | Description |
card_number | Optional |
| Must be valid card number |
card_format_name | Optional | Card format must exist in Genea | If the specified card format is not available in Genea, the system will create the card without applying any format. |
card_facility_code | Optional |
| Facility code of the card. |
card_badge_type_name | Optional | Badge type must exist in Genea | If the specified badge type exists in Genea, it will ignore the card_activation_time_utc and card_deactivation_time_utc values from the CSV and create the key card using the provided badge type.
If the specified badge type does not exist in Genea, it will override the badge type settings and create the card based on the card_activation_time_utc and card_deactivation_time_utc values. |
card_activation_time_utc | Optional | UTC timestamp | If not specified, defaults to current UTC time. |
card_deactivation_time_utc | Optional | UTC timestamp | If not specified, card has no expiration. |
card_status | Optional | ACTIVE INACTIVE DELETE | If not specified, defaults to ACTIVE.
If the card already exists with provided card_number, it will update the card record.
|
5.4 PIN Fields
CSV Header | Required / Optional | Valid Value | Description |
pin_number | Optional |
| Must be valid PIN. |
pin_badge_type_name | Optional | Badge type must exist in Genea | If the specified badge type exists in Genea, the system will ignore the pin_activation_time_utc and pin_deactivation_time_utc values from the CSV and create the PIN using the provided badge type. If the specified badge type does not exist in Genea, the system will override the badge type settings and create the PIN based on the pin_activation_time_utc and pin_deactivation_time_utc values. |
pin_activation_time_utc | Optional | UTC timestamp | If not specified, defaults to current UTC time. |
pin_deactivation_time_utc | Optional | UTC timestamp | If not specified, PIN has no expiration. |
pin_status | Optional | ACTIVE DELETE | If pin_status is not specified in the CSV, the system will default the status to ACTIVE.
ACTIVE: If the PIN does not exist, the system will create a new PIN for the user. If the PIN already exists with provided pin_number, the system will update the PIN record.
DELETE: The system will delete the PIN record. |
6. File Processing Flow in Genea
Once the CSV file is uploaded to the root directory:
The system automatically picks up the file within 15 minutes.
After processing, the file is moved to the processed folder.
A new sync_result file is generated for the processed file.
Only files uploaded at the root level are processed.
Viewing Sync Results
To review the results:
Download the generated sync_result file from the processed folder.
Review the sync_status_remark column for each record.
For example, if you have uploaded the users_202602230502.csv file, the system will process it and move it to the processed folder, and you can review the sync result by downloading the users_202602230502_sync_result.csv file.
This column indicates the success or failure details for each processed record.
7. Validation Rules
During processing, the system validates:
Required headers are present
Mandatory fields are populated
Unique
external_idValid email format (if provided)
Valid card number format
Valid PIN format
Existing badge types (if specified)
Existing user groups (if specified)
Invalid records may be ignored during processing.