Skip to main content

SFTP Integration Guide

A comprehensive guide to setting up and using SFTP (Secure File Transfer Protocol) for bulk data operations with Oho, including file-based imports, exports, and automated integrations.

Overview​

Base URL: sftp://sftp.weareoho.com

Authentication: SSH key-based authentication (recommended) or username/password

Port: 22 (default SFTP port)

This guide covers everything you need to set up secure file transfers for bulk operations with Oho, including constituent imports, accreditation exports, and automated data synchronization.

Why Use SFTP with Oho?​

SFTP provides a secure, reliable way to handle bulk data operations that complement the Oho API:

  • ✅ Bulk imports - Upload hundreds or thousands of constituents via CSV files
  • ✅ Scheduled exports - Automated daily/weekly data exports for reporting
  • ✅ Large file transfers - Handle files too large for standard API requests
  • ✅ Legacy system integration - Connect older systems without REST API capabilities
  • ✅ Audit trails - Complete file transfer logs and history
  • ✅ Secure encryption - Industry-standard SSH encryption for data in transit

Prerequisites​

Before You Begin

Ensure you have:

  • Active Oho account with SFTP access enabled (contact Oho Support to request)
  • SFTP client installed (FileZilla, Cyberduck, or command-line sftp)
  • SSH key pair generated (recommended for production use)
  • Understanding of CSV file formats for bulk operations
  • Valid API authentication token for validation operations
SFTP Access Required

SFTP access must be enabled for your Oho account before you can use it. Contact Oho Support to request SFTP credentials and setup instructions for your organization.

Understanding SFTP​

What is SFTP?​

SFTP (SSH File Transfer Protocol) is a secure file transfer protocol that runs over SSH. It provides encrypted file transfers and is the industry standard for secure data exchange.

Key differences from FTP:

  • Encrypted connection (vs plain text)
  • Single port (22) vs multiple ports
  • Built on SSH protocol
  • Better firewall compatibility

When to Use SFTP vs API​

Use SFTP when:

  • Regularly importing/exporting 1000+ records at once
  • Integrating with legacy systems without API support
  • Scheduling automated daily/weekly data synchronization
  • Transferring large data sets or attachments
  • Your workflow involves file-based processing

Use REST API when:

  • Making real-time individual requests
  • Building interactive applications
  • Receiving webhook notifications
  • Performing single record operations
  • Need immediate response validation

SFTP Workflow with Oho​

Prepare Data File → Connect via SFTP → Upload to Dropbox → Oho Processes File
                                                              ↓
                                                    Validation Report Generated
                                                              ↓
                                                    Download Results via SFTP

Setting Up SFTP Access​

Request SFTP Credentials​

Contact Oho Support to request SFTP access. You'll receive:

  • SFTP hostname (e.g., sftp.weareoho.com)
  • Username (typically your organization identifier)
  • Initial temporary password
  • Instructions for SSH key setup

Directory Structure​

Once connected, you'll see a standardized directory structure for bidirectional data flow:

/
├── upload/              # YOUR SYSTEM → OHO (import to Oho)
    └── archive          # store of old files
├── download/            # OHO → YOUR SYSTEM (export from Oho)
    └── archive          # store of old files

Directory Purpose​

upload/ - Files your system sends to Oho:

  • Place files here for Oho to import and process
  • Oho automatically detects new files and begins processing
  • File selection policy: Oho processes the most recently created file of each type
  • Processed files are automatically moved to upload/archive/ after completion
  • Failed files remain in place with error reports generated

download/ - Files Oho generates for your system:

  • Credential status updates (e.g., daily status file)
  • Validation results and processing reports
  • Scheduled compliance exports
  • Download these files regularly to sync Oho data back to your system

Upload File Types​

Oho accepts one required file and one optional file for upload:

1. Employee and Credential File (Required)​

Contains your active employees and their credentials. See detailed schema below.

2. Position Requirements File (Optional)​

Contains position-to-license mappings. Only needed if your organization has specific license requirements per position/role. See detailed schema below.

Note: Not all organizations use position requirements. Contact Oho Support to determine if this applies to your use case.

File Naming Conventions​

Oho uses standardized file naming patterns to identify file types and processing order:

<source>-<type>-<timestamp>.csv

Components:

  • <source> - Your organization or system identifier (e.g., "HRMS", "PayGlobal", "MyOrg")
  • <type> - File content type (optional - use if uploading position requirements)
    • Omit for employee/credential file
    • Use POS for position requirements file
  • <timestamp> - ISO format timestamp (YYYYMMDD_HHMMSS) or date (YYYYMMDD)

Examples:

HRMS-20260129_143000.csv          # Employee & credential import (required)
HRMS-POS-20260129_143000.csv      # Position requirements (optional)
Oho-20260129_143000.csv           # Oho status export

File Selection Policy​

How Oho processes files:

  • Oho selects the most recently created file of each type in the upload directory
  • Files are processed based on modification timestamp (newest first)
  • Employee/credential file and position file are processed independently
  • Wait for processing to complete before uploading the next batch
  • Frequency: Files are typically processed daily, but contact Oho Support for custom scheduling

Best practices:

  • Use consistent naming patterns for reliable processing
  • Include timestamps to ensure proper ordering
  • Don't reuse filenames (creates ambiguity)
  • Archive old files locally after successful processing

File Formats and Specifications​

General CSV Requirements​

All CSV files must follow these standards:

RequirementSpecification
FormatCSV (Comma-Separated Values)
EncodingUTF-8 (without BOM)
Header RowRequired - first row must contain column names
DelimiterComma (,)
String DelimiterDouble quotes (") - all values should be quoted
Line EndingCRLF (\r\n) or LF (\n)
Date FormatYYYY-MM-DD (ISO 8601)
Maximum Rows10,000 per file (split larger datasets)

Example formatting:

"external_id","first_name","last_name","email","date_of_birth"
"EMP001","Sarah","Chen","sarah.chen@example.com","1992-03-15"
"EMP002","Michael","Wong","michael.wong@example.com","1988-07-22"

Important:

  • All values must be string-delimited (wrapped in double quotes)
  • Dates must use YYYY-MM-DD format
  • Empty values should be represented as "" (empty string), not left blank

Employee and Credential Import CSV​

Oho accepts a single file format that combines employee data with their credentials. Each row represents one credential per employee (employees with multiple credentials appear on multiple rows).

Required Fields:

FieldTypeDescription
external_idStringUnique employee identifier from your system (part of primary key)
first_nameStringFirst/given name
last_nameStringLast name/surname
dobDate (YYYY-MM-DD)Date of birth
emailStringEmail address (must be unique)
position_idStringPosition/role identifier
licence_typeStringType of credential/license (part of primary key)
licence_numberStringCredential/license number (part of primary key)
issue_dateDate (YYYY-MM-DD)Credential issue date
expiry_dateDate (YYYY-MM-DD)Credential expiry date

Optional Fields:

FieldTypeDescription
middle_nameStringMiddle name(s)

Example Import File:

"external_id","pageup_id","first_name","middle_name","last_name","dob","email","position_id","licence_type","licence_number","issue_date","expiry_date"
"EMP001","","Sarah","Jane","Chen","1992-03-15","sarah.chen@example.com","RN-001","AHPRA","NMW0001234567","2020-06-01","2026-05-31"
"EMP001","","Sarah","Jane","Chen","1992-03-15","sarah.chen@example.com","RN-001","VICWWC","1234567A","2023-01-15","2028-01-14"
"EMP002","PU-2024-001","Michael","","Thompson","1988-07-22","michael.thompson@example.com","DOC-001","AHPRA","MED0001234567","2015-03-01","2026-05-31"
"EMP003","","Jessica","Marie","Martinez","1995-11-08","jessica.martinez@example.com","EN-001","NDIS","NDIS-789012","2024-01-01","2029-01-01"

Primary Key: external_id + licence_type + licence_number

Important Notes:

  • Each row represents ONE credential
  • Employees with multiple credentials appear on multiple rows with repeated personal data
  • Employee fields (name, email, dob, etc.) should be identical across all rows for the same external_id

Active/Inactive Logic:

  • Only active employees should be included in the upload file
  • Employees not present in the file but existing in Oho will be marked as inactive/deactivated
  • This "by exclusion" approach ensures Oho stays synchronized with your source system
  • To reactivate an employee, include them in a subsequent upload

Validation Rules:

  • external_id must be unique per employee in your system
  • email must be valid format and unique within organization
  • All date fields must use YYYY-MM-DD format
  • Primary key combination (external_id + licence_type + licence_number) must be unique

Credential Status Export (Download from Oho)​

Oho generates credential status files for your system to consume. These files contain the current state of all active credentials in Oho.

Fields in Status Export:

FieldTypeRequiredDescription
external_idStringTrueEmployee identifier (matches your system)
licence_typeStringTrueType of credential
licence_numberStringTrueCredential number
issue_dateDate (YYYY-MM-DD)TrueCredential issue date
expiry_dateDate (YYYY-MM-DD)FalseCredential expiry date (if applicable)
licence_statusStringTrueOho status: green, yellow, red

Example: Status Export

"external_id","licence_type","licence_number","issue_date","expiry_date","licence_status"
"EMP001","AHPRA","NMW0001234567","2020-06-01","2026-05-31","green"
"EMP001","VICWWC","1234567A","2023-01-15","2028-01-14","green"
"EMP002","AHPRA","MED0001234567","2015-03-01","2026-05-31","yellow"
"EMP003","VICWWC","9876543Z","2020-05-01","2025-05-01","red"

Licence Status Values:

  • green - Valid and current, no action needed
  • yellow - Needs attention (expiring soon, renewal pending, has conditions, non-practising)
  • red - Invalid, expired, suspended, or cannot practice

Usage:

  • Download this file from /download/ directory
  • Import into your HR/payroll system
  • Use to flag compliance issues and trigger renewals
  • Only active credentials are included (inactive/deleted credentials are excluded)

Position Requirements CSV (Optional Upload to Oho)​

When to use: Only if your organization has specific license requirements per position/role. This file defines which licenses are required for each position, allowing Oho to validate employee compliance based on their assigned role.

Required Fields:

FieldTypeRequiredDescription
position_idStringTruePosition/role identifier (matches position_id in employee file)
license_codeStringTrueCode of the license required for this position

Optional Fields:

FieldTypeRequiredDescription
stateStringFalseState where position operates (required for state-specific licenses like driver's licenses, WWC)

Example: Position Requirements File

"position_id","license_code","state"
"RN-001","AHPRA",""
"RN-001","VICWWC","VIC"
"RN-001","NDIS",""
"DOC-001","AHPRA",""
"DOC-001","VICWWC","VIC"
"EN-001","AHPRA",""
"EN-001","QLDWWC","QLD"
"DRIVER-001","DL-VIC","VIC"

How it works:

  • Each row maps ONE license requirement to ONE position
  • Positions with multiple requirements appear on multiple rows (normalized table)
  • Oho uses this to automatically flag compliance gaps when employees are assigned to positions
  • When an employee's position_id is set, Oho validates they have all required licenses for that position

File naming: <source>-POS-<timestamp>.csv

Important:

  • This file is optional - only upload if you have position-specific license requirements
  • The license_code values must match the licence_type values used in your employee/credential file
  • For state-specific licenses (WWC, driver's licenses), include the state field
  • Contact Oho Support to discuss if position requirements apply to your use case

Configuration and Mappings​

Licence Type Mappings​

Before uploading data, you must configure how your system's licence types map to Oho's verification types.

Process:

  1. Provide Oho Support with your list of licence types (as they appear in licence_type field)
  2. Oho configures the mapping between your codes and Oho's verification types
  3. Any new licence types require a mapping request to Oho Support

Example Mappings:

Your licence_type CodeDescriptionOho Verification Type
RN-AHPRARegistered Nurse AHPRAahpra
VIC-WWCCVictoria WWCvicwwc
QLD-BLUEQueensland Blue Cardqldblue
NDIS-WORKERNDIS Worker Screeningndis

Important:

  • Mappings are configured per organization before go-live
  • All licence types must be mapped before they can be processed
  • Contact Oho Support to add new licence types
  • Use consistent codes in all your uploads
  • Test mappings before production use

Processing Frequency​

Default Schedule:

  • Files are processed daily (typically overnight)
  • Processing starts when new files are detected in upload directories
  • Results are available within 1-4 hours after processing begins

Custom Schedules:

  • Contact Oho Support for different processing frequencies
  • Available options: hourly, twice-daily, weekly
  • Real-time processing available for critical workflows

Status Synchronization​

How bidirectional sync works:

YOUR SYSTEM                    OHO
    │                           │
    │  1. Upload single CSV     │
    ├──────────────────────────>│
    │     (employees +           │
    │      credentials)          │
    │                           │
    │  2. Oho verifies all      │
    │     credentials            │
    │                           │
    │  3. Download status       │
    │<───────────────────────────┤
    │     export CSV             │
    │                           │
    │  4. Update your           │
    │     system with           │
    │     Oho statuses          │

Recommended workflow:

  1. Daily upload - Send ONE CSV file with active employees and all their credentials
  2. Oho processes - Verifies credentials against registries (AHPRA, WWC, NDIS, etc.)
  3. Daily download - Retrieve status export CSV with updated credential statuses
  4. Sync back - Import status file into your HR/payroll system
  5. Alerts - Flag any red or yellow status credentials for review

Troubleshooting​

File Upload Issues​

Problem: "No such file or directory" when uploading​

Cause: Target directory doesn't exist or incorrect path

Solutions:

  1. ✅ List directories: ls -la
  2. ✅ Navigate to correct upload directory: cd upload/constituents
  3. ✅ Verify file exists locally: !ls -l constituents.csv
  4. ✅ Use absolute paths in put command

Problem: File uploads but never gets processed​

Cause: Invalid file format or naming convention

Solutions:

  1. ✅ Check file naming follows convention (e.g., constituents_*.csv)
  2. ✅ Verify CSV format matches template
  3. ✅ Check file encoding is UTF-8
  4. ✅ Ensure no hidden characters or BOM
  5. ✅ Download templates from /templates directory

FAQ​

Q: How long does it take for uploaded files to be processed?​

A: Processing time depends on file size:

  • Small files (< 100 rows): 2-5 minutes
  • Medium files (100-1,000 rows): 5-15 minutes
  • Large files (1,000-10,000 rows): 15-30 minutes

You'll know processing is complete when the file moves from upload/ to upload/archive/ and results appear in download/results/.

Q: Can I schedule automated uploads?​

A: Yes, use cron (Linux/macOS) or Task Scheduler (Windows) to automate uploads. See "Workflow 2: Automated Daily Export" for examples.

Q: How long are files retained on the SFTP server?​

A:

  • upload/: Processed files moved to archive after processing
  • upload/archive/: Retained for 30 days
  • download/: Files retained for 90 days
  • Contact Oho Support for different retention requirements

Q: Can I use SFTP for real-time integrations?​

A: SFTP is designed for batch operations, not real-time. For real-time integrations, use the REST API and Webhooks.

Q: What file size limits apply?​

A:

  • Maximum file size: 100MB per file
  • Maximum rows: 10,000 per CSV file
  • For larger data sets, split into multiple files

Q: Can I automate downloads of new result files?​

A: Yes, use a script that polls the download/results/ directory for new files. See "Workflow 4: Monitoring Upload Processing" for an example.

Q: What if I need to cancel a file upload?​

A: If a file is still in the upload directory and hasn't been processed yet, you can connect via SFTP and delete it:

Q: How does bidirectional sync work?​

A: Bidirectional sync enables two-way data flow:

  1. Your system → Oho (upload/): Send active employees and credentials daily
  2. Oho → Your system (download/): Receive updated credential statuses daily
  3. Import Oho's status export to keep your HR system synchronized with current verification statuses

This ensures your source system always reflects the latest credential validation results from Oho.

Q: How do I set up licence type mappings?​

A: Contact Oho Support with:

  1. Your list of licence types (as they appear in the licence_type field)
  2. Description of each licence type
  3. Which Oho verification type each should map to

Oho will configure the mappings and confirm when ready for testing. All licence types must be mapped before go-live.

Q: What file naming convention should I use?​

A: Follow these patterns:

Required file (employees & credentials):

  • <source>-<timestamp>.csv
  • Example: HRMS-20260129_143000.csv

Optional file (position requirements):

  • <source>-POS-<timestamp>.csv
  • Example: HRMS-POS-20260129_143000.csv

Download file (Oho status export):

  • Oho-<timestamp>.csv
  • Example: Oho-20260129.csv

Use consistent naming for reliable processing. Include timestamps to ensure proper ordering.

Q: Do I need to upload the position requirements file?​

A: Only if your organization has specific license requirements per position/role. Many organizations don't use this feature. Contact Oho Support to determine if position requirements apply to your use case.

Support​

For questions or issues with SFTP integration:

  1. Verify connection with verbose output: sftp -vvv oho-sftp
  2. Check file formats against templates in /templates directory
  3. Review results files in /download/results for error details
  4. Contact Oho Support with:
    • Your username
    • Timestamp of upload/download
    • Filename experiencing issues
    • Error messages or logs

Version: 1.0 Last Updated: 2026-01-29 Status: Production Ready