No native migration path exists between Humaans and Officient. API-to-API extraction with custom transformation is required. Budget for compensation model mismatches, time-off policy flattening, and Officient's tight 30 req/5 sec rate limit.
Migrating from Humaans to Officient requires a full extract-transform-load (ETL) process, as no native migration path exists between the two platforms. Humaans is an API-first, globally-oriented HRIS built on a deeply decomposed object model with 30+ resource types and foreign-key relationships, while Officient is a Belgian-rooted, SME-focused platform with a flatter, schema-on-write data structure that enforces strict validation at the point of entry. Data that exists comfortably across Humaans's separate resources for Compensations, Time Away, Bank Accounts, and Custom Fields must be denormalized, cleaned, and reassembled to conform to Officient's predefined relational constraints before it will be accepted. Every migration requires extraction via the Humaans API or CSV export, custom transformation logic to resolve schema incompatibilities, and loading into Officient via its REST API or manual import in a strict creation order.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
If you run both systems concurrently, ensure payroll data lives in only one system at a time
Split-brain payroll data leads to compliance violations. Back up raw Humaans exports outside the platform — data export objects expire after a short period.
Rate limit math
At 30 requests per 5 seconds (6 req/sec sustained), creating 200 employees with their job roles, wages, and time-off records requires roughly 5–6 API calls per employee (create person + update manager + set role + set wage + create days off + custom fields = ~6 calls). That's 1,200 calls ÷ 6 req/sec = 200 seconds minimum, or ~3.3 minutes at full throttle with zero errors. For 500 employees: 3,000 calls ÷ 6 req/sec = 500 seconds = ~8.3 minutes minimum. Factor in retries, validation calls, and document uploads, and a 500-employee migration load phase can take 30–60 minutes. Your pipeline must implement exponential backoff and checkpoint every batch.
Signed contracts
If you're migrating already-signed employment agreements, Officient's contract API supports presigned_pdf. Load historical signed files as presigned_pdf rather than re-sending them for signature.
This is a structural outline demonstrating the pattern, not production-ready code
A real migration script additionally needs: structured logging with correlation IDs, a dry-run mode that validates without writing, integration tests against an Officient sandbox, and a final reconciliation report comparing source and target record counts per entity type.
The runbook
Work top to bottom. Tick steps as you go — your progress is saved in this browser.
01 Discovery Scope candidates, pipelines and the compliance obligations that come with them.
Objective Agreed scope across candidates, applications, jobs and interview history, with legal signed up on retention.
Keep these open
-
Inventory every object in Humaans
Count candidates, applications (a candidate can have many), jobs and requisitions, interviews, scorecards, offers, and resume files. Applications and scorecards usually outnumber candidates several times over, and resume files dominate storage.
Data Profiler Get real record counts instead of estimating from memory -
Settle retention and consent with legal
Candidate data is heavily regulated: GDPR right-to-erasure, EEOC/OFCCP record-keeping, and per-region retention windows that conflict with each other. Decide what may be migrated at all before you scope anything else — this frequently shrinks scope substantially.
Migrating candidate records whose consent has lapsed or whose retention window has expired creates a new compliance breach in the target system.
-
Map the hiring pipeline and agree the target stages
Document every job's pipeline, stage, and rejection reason, then agree the Officient model with talent leadership. Stage definitions drive every funnel metric you report, so changing them silently rewrites your hiring analytics.
-
Catalogue integrations and the job-board estate
List job boards, careers-site integration, HRIS, background check, assessment platforms, calendar and email. The careers site and job boards are customer-facing, so their cutover needs its own plan and its own testing.
-
Build the business case and choose the window
Model licence delta, effort and recruiter productivity dip. Time the window against your hiring cycle: a migration during peak graduate recruitment or a hiring surge will fail on people, not technology.
Vendor Evaluator Score Officient against alternatives on weighted criteria
Humaans → Officient specifics
- Belgian/Benelux payroll compliance
- Officient has native integrations with Belgian payroll providers including SD Worx, Securex, Partena Professional, Nmbrs, and The Payroll Office. If your company is consolidating operations into Belgium or the Netherlands, Officient's payroll pipeline is significantly more mature for that region — including handling Belgian DIMONA declarations and NISS/INSZ national number validation.
- Cost consolidation
- Smaller teams (25–200 employees) in Western Europe often find Officient's pricing better aligned with their headcount and feature requirements.
- Exact ecosystem
- Companies already using Exact Online for accounting want a single-vendor HR stack with native data flow between finance and HR.
- Simpler administration
- Teams that don't need Humaans's API-first extensibility may prefer Officient's more guided, workflow-driven approach to employee management, including built-in onboarding flows, contract generation, and self-service portals.
- Relationship-aware
- We rebuild manager hierarchies, department structures, and reporting lines — the data that breaks silently in CSV exports.
Don't move on until
- Counts confirmed for candidates, applications, jobs and offers
- Retention and consent obligations confirmed with legal
- Hiring-stage model agreed with talent leadership
02 Data Audit Audit candidate data with compliance sitting next to you.
Objective Profiled exports with duplicates, expired records and resume files all quantified and triaged.
Keep these open
-
Export and profile candidates, applications and jobs
Profile each object separately and reconcile against API counts. Watch the candidate-to-application ratio: a mismatch usually means applications have been silently truncated by pagination.
Data Profiler Profile the Humaans export for nulls, outliers and type drift -
Quantify duplicate candidates and agree survivorship
The same person applies repeatedly over years with different emails and name spellings. Measure the duplicate rate and agree survivorship rules — which record wins and what happens to the application history attached to the losers.
Merging candidates without agreed survivorship rules destroys application and interview history that you may be legally required to retain.
Data Cleaner Strip empty rows, stray whitespace and dead columns -
Identify records outside their retention window
Flag candidates whose consent has expired, who have exercised erasure, or who fall outside regional retention. Exclude them from scope and document the exclusion — you need to show the decision was deliberate.
PII & Compliance Scanner Find regulated fields before they land in a new system -
Inventory resume files and attachments
Count files, total volume and MIME types, and check every attachment still resolves to a live URL. Expiring signed download URLs are the classic reason a resume migration completes with a large fraction of empty files.
Resume download URLs are often short-lived signed links. Fetch files close to load time or they will 404 mid-migration.
-
Verify relationship integrity
Confirm every application links to a live candidate and a live job, and every scorecard to a real interview. Orphaned applications produce a funnel report that does not tie to anything.
-
Clean, normalise and produce masked test data
Normalise emails, phone formats and locations, standardise timestamps to UTC, and generate a masked dataset for the sandbox. Real candidate data in a sandbox is a compliance breach in most jurisdictions.
PII Masker Generate a safe copy for sandbox and vendor testing -
Document audit
Confirm file counts per employee match. Open sample documents to verify they're not corrupted.
Humaans → Officient specifics
- Rate limit management
- We've built throttling and retry logic for both APIs, including handling Officient's missing Retry-After header.
Don't move on until
- Duplicate candidate rate quantified with a merge policy agreed
- Records outside retention identified and excluded
- Resume and attachment inventory complete with total volume
03 Field Mapping Map the candidate-application-job triangle before anything else.
Objective A signed mapping covering objects, stages, rejection reasons, scorecards and EEO fields.
Keep these open
-
Map the candidate, application and job model
ATS platforms differ on whether a person or an application is the primary record. Establish this first: getting it wrong means one candidate becomes five, or five applications collapse into one, and the entire field map has to be redone.
Candidate-centric and application-centric models are not interchangeable. Confirm which Officient uses before mapping any field.
Schema Mapper Opens pre-loaded with the Humaans → Officient field pair -
Map pipeline stages and rejection reasons exhaustively
Enumerate every stage and rejection reason across all jobs, including retired values on historical applications, and map each explicitly. Unmapped rejection reasons are both a reporting gap and, in regulated hiring, a compliance one.
-
Decide EEO and diversity data handling
These fields are separately regulated and often legally required to be stored apart from the candidate record. Confirm with legal whether they migrate at all, and how Officient isolates them.
EEO data usually cannot be migrated into ordinary custom fields without breaching the segregation rules that govern it.
-
Map interviews, scorecards and feedback
Structured scorecards rarely have a native equivalent. Decide whether to reconstruct them, flatten them into notes, or keep them only in the archive — and be explicit that flattening loses the ability to report on them.
JSON to CSV Converter Flatten nested API responses into a reviewable sheet -
Plan resume and file migration
Confirm size limits, MIME support and whether Officient re-parses resumes on upload. Re-parsing can overwrite carefully curated candidate fields with worse machine-extracted values, so test it deliberately.
-
Set load order and freeze the spec
Users, then jobs, then candidates, then applications, then interviews and scorecards, then files. Keep source IDs in custom fields, then version and sign off the spec.
-
Build location and department mappings
Map Humaans locationId and department strings to Officient IDs.
-
Normalize person data
Convert gender values (Humaans is free-text; Officient may require specific values), employee types (free-text contractType → Officient's enum: employee, freelancer, student_worker, intern), address formatting, and phone numbers.
Data Format Converter Reshape the export into the format Officient's importer expects -
Flatten compensation
Extract the currently active compensation per type using effectiveDate sorting. Convert to Officient's wage format. Parse amount from string to number.
Humaans → Officient specifics
- Custom field mapping
- We handle Humaans's typed custom fields (text, select, multiSelect, date, person) and map them to Officient's schema, transforming data types where needed.
- Transform custom fields
- Map Humaans custom field IDs to Officient custom field IDs. Convert data types where needed. Flatten unsupported types (person → employee name string, multiSelect → comma-separated string, longText → text, link → text).
- Custom field verification
- Check all custom field values transferred correctly, especially select_option types where value mapping may have introduced errors.
Don't move on until
- Candidate/application/job model mapped and reviewed
- Every stage and rejection reason explicitly mapped
- EEO and diversity field handling agreed with legal
04 Test Migration Pilot whole candidate journeys, not isolated records.
Objective A sandbox pilot where candidate journeys, funnel metrics and resume files all verify.
Keep these open
-
Configure the Officient sandbox with the agreed pipelines
Create jobs, pipeline stages, scorecard templates, user roles and custom fields first. Loading applications before the stages exist puts every candidate in a default stage and invalidates the pilot.
-
Select complete candidate journeys as the pilot slice
Take 100-200 candidates with all their applications, interviews, scorecards and files — including repeat applicants, hires, rejections at every stage, and candidates on multiple jobs. Repeat applicants are where the model mapping actually gets tested.
-
Run the load in dependency order with logging
Jobs, candidates, applications, interviews, then files, logging each request against its source ID. Track file uploads separately: they fail for different reasons and at different rates than record writes.
-
Verify journeys and funnel metrics
Confirm each candidate sits at the right stage on the right job with their history intact, and that per-stage funnel counts match Humaans for the pilot jobs. Funnel mismatches point straight back to stage mapping.
Migration Validation Tool Diff the pilot batch against source before scaling up -
Open every pilot resume and check re-parsing
Actually open the files rather than trusting the upload count, and check whether re-parsing has overwritten any candidate fields. A resume that uploaded as a zero-byte file still counts as a success in most logs.
-
Put recruiters in front of the pilot data
Have recruiters work their own pilot requisitions end to end. They immediately spot missing feedback, wrong stages and unreadable history that reconciliation cannot see.
Don't move on until
- Candidate-application-job relationships intact for the pilot
- Funnel counts per stage match source for pilot jobs
- Resume files open correctly for every pilot candidate
05 Cutover Switch recruiting without dropping a live candidate.
Objective All in-scope recruiting data live in Officient, careers site and boards repointed, recruiters working.
Keep these open
-
Pre-load historical candidates and closed jobs
Load closed requisitions, rejected candidates and archived applications while Humaans stays live. Only active pipeline and the final delta need to move in the window.
-
Publish the runbook including the careers-site switch
A timed sequence with owners and abort criteria, treating the careers site and job boards as first-class steps. They are candidate-facing, so a failure there is publicly visible in a way a data defect is not.
-
Freeze Humaans and take the final delta
Stop new applications and let recruiters finish in-flight actions, then export everything changed since the pre-load. Coordinate with anyone actively interviewing so feedback is not entered into the old system mid-freeze.
Interview feedback entered in the old ATS during the freeze is lost, and it is the data recruiters most immediately notice missing.
-
Load active pipeline and reconcile stages
Load active candidates and applications, then verify every active candidate is at the correct stage on the correct job before repointing anything. Active-stage accuracy is what recruiters check first on day one.
Migration Validation Tool Confirm the final delta landed before you reopen -
Repoint careers site, job boards and integrations
Switch the careers-site integration, repost or migrate live job ads, and repoint HRIS, background check, assessment and calendar integrations. Then submit a real test application through the careers site and every major board.
Job ads left posted against the old ATS keep collecting applications that never reach the new system.
-
Go/no-go and switch recruiters over
Call the decision against the exit criteria, then move recruiters with support on hand for the first day. Keep Humaans read-only — candidate records have retention obligations that outlast the migration.
-
Record count parity
Count(Humaans.People) == Count(Officient.People) for both active and offboarded
Humaans → Officient specifics
- Field-level sampling
- Pick 20 random employees. Verify every mapped field matches — including salary, start date, manager, department, custom fields, employee type, and national number.
- Compensation spot-check
- Verify current salary, currency, and period for all employees
- Failed record review
- Review the dead letter queue for any records that failed to load. Resolve root causes and reload.
Don't move on until
- Historical load complete and reconciled before the freeze
- Careers site and job boards posting into Officient and verified
- Active candidates confirmed at the correct stage
06 Validation Prove the funnel, the files and the compliance position.
Objective Reconciled recruiting data, funnel parity with baseline, and a defensible compliance record.
Keep these open
-
Reconcile every object including files
Compare counts for candidates, applications, jobs, interviews, scorecards and files, with field-level spot checks on a sample. Count files separately — they are the object most likely to be quietly short.
Migration Validation Tool Reconcile Humaans and Officient record-for-record -
Tie funnel and time-to-hire reporting to baseline
Rebuild funnel conversion, time-to-hire, source effectiveness and offer-acceptance reporting and compare to pre-migration figures. Variances trace back to stage mapping and to how application timestamps were handled.
Time-to-hire depends on stage-transition timestamps. If those were approximated, the metric will differ even with identical records.
-
Verify file integrity at scale
Sample-open resumes across the whole load and compare file sizes against source. Zero-byte and truncated files are common and never surface in an upload success count.
-
Confirm retention, consent and EEO configuration
Verify retention rules, consent state and EEO segregation are correctly configured in Officient, and that excluded records genuinely did not migrate. File this as your compliance evidence.
PII & Compliance Scanner Produce the compliance evidence your auditor will ask for -
Test workflow, notifications and candidate-facing paths
Fire every stage automation, interview scheduling flow, rejection template and offer approval, and submit a live application through the careers site. Candidate-facing emails going out wrong is a brand problem, not just a bug.
-
Sign off and schedule decommission
Get written acceptance against the Discovery criteria, retain Humaans read-only for the period your retention policy requires, take a final archive export, and diarise cancellation.
-
Validate national identification numbers
For Belgian employees, validate the NISS/INSZ checksum. For employees born before 2000: 97 - (first_9_digits mod 97) == last_2_digits. For employees born 2000+: 97 - ((2_prepended_to_first_9_digits) mod 97) == last_2_digits. Flag invalid numbers for manual correction.
-
Record counts
Compare total people (active + offboarded) in both systems.
-
Rebuild workflows
Officient workflows (onboarding, offboarding) are configured separately from Humaans and won't transfer. Recreate them manually.
Humaans → Officient specifics
- Field-level spot check
- Sample 10–20% of employees and verify every mapped field — salary, start date, manager, department, custom fields, employee type, national number.
- Manager hierarchy
- Confirm reporting lines are correct for every manager. Traverse the full hierarchy from CEO to individual contributors.
- Compensation
- Verify current salary, currency, and period matches for all employees.
- Time-off balances
- If carried over, confirm balances match Humaans's computed values from /api/time-away-periods.
- Employee type verification
- Confirm every employee has the correct type in Officient, as this directly affects payroll calculation.
Don't move on until
- Reconciliation complete across candidates, applications and files
- Funnel and time-to-hire reporting tie to baseline
- Retention and EEO configuration verified, acceptance signed
Field mapping reference
The field-by-field mapping for each object. Use this as the starting point for your mapping spec.
Object Equivalent
| Humaans field | Officient field | Notes |
|---|---|---|
| Person | People (person detail) | Core employee record. Most fields map 1:1 but naming differs. Officient requires specific national identification formats depending on the country — Belgian NISS/INSZ is 11 digits with modulo-97 checksum. |
| Person.contractType | Employee type | Humaans is free-text. Officient requires specific types: employee, freelancer, student_worker, intern. These affect payroll calculation logic. |
| Company | Account / Organization | Officient ties to a single account. |
| Location | Office / Location | Humaans has rich location objects with timezone and holiday calendar. Officient handles this differently. |
| Job Role | Role History | Humaans has effective-dated roles with department, title, manager. Map to Officient's role update endpoint. |
| Compensation | Current Wage / Components | Major structural mismatch. Humaans stores compensation as separate objects with effective dates. Officient uses wage + monthly components. See detailed section below. |
| Time Away | Days Off | Humaans has entries, types, policies, allocations, periods, adjustments. Officient has a simpler days-off structure. |
| Equipment | Assets | Roughly equivalent. Both track type, name, serial number, cost. |
| Documents | Documents | Both support file attachments. File transfer requires download from Humaans + re-upload to Officient. Officient documents are scoped to employee, asset, or car. |
| Bank Account | Banking details (within person) | Humaans has a separate resource. Officient may store this inline or through payroll integration. |
| Custom Fields + Custom Values | Custom fields | Humaans supports 7 field types; Officient supports 6. Custom fields must be created in Officient (via API or UI) before values can be loaded. This is a hard dependency in the load order. |
| Working Pattern + Allocation | Weekly Schedule | Humaans has multi-week patterns with FTE calculation. Officient uses a simpler weekly schedule. |
| Emergency Contact | Emergency contact data | Straightforward mapping. |
| Identity Document | ID document data | Passport, visa, driving license records. Map expiry dates explicitly so automated alerts continue to function. |
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Employee Core Profiles | medium | Core people records map between platforms but field count differences (Humaans has 50+ person fields vs. Officient's flatter model) mean some profile attributes may have no target field and will require custom field mapping or be discarded. |
| Job Role History | medium | Both platforms support role history with effective dating, but the structural differences between Humaans's separate Job Roles resource and Officient's Role History endpoint require explicit transformation and ID remapping to preserve historical sequences. |
| Compensation History | high | Humaans maintains full multi-type compensation history with effective dates, while Officient's wage model is flatter and present-focused, meaning historical compensation records beyond current values are at high risk of loss without a purpose-built transformation strategy. |
| Time-Off Balances and History | high | The five-layer Humaans time-off hierarchy cannot be cleanly mapped to Officient's simpler Days Off structure, and accrued balances, adjustments, and historical periods are at significant risk of data loss or miscalculation during migration. |
| Custom Fields and Values | medium | Humaans supports seven custom field types while Officient supports six with different type names, so most field types can be mapped, but multiSelect and link types have no direct equivalent and must be converted or dropped before loading. |
| Documents and Files | medium | Document metadata can be migrated via API, but binary file content requires separate download and re-upload handling, and Humaans's typed folder structure does not map directly to Officient's employee-record-attached document model. |
| Equipment and Assets | low | Both platforms support equipment or asset tracking with similar attributes such as serial numbers and costs, making this one of the more straightforward entity mappings in the migration. |
| Bank Accounts | high | Bank account data is sensitive financial information requiring strict access controls and encryption in transit; Humaans exposes this via a dedicated API resource with no direct Officient equivalent field mapping documented, increasing both compliance and data loss risk. |
| Manager Hierarchies and Relationships | medium | Manager-to-employee relationships stored as foreign key references in Humaans must be rebuilt using an ID mapping table during migration, and any employees loaded out of order will break referential integrity until the full dataset is loaded. |
| Contracts | high | Officient enforces a strict non-overlapping contract date validation rule at write time, meaning any gaps, overlaps, or missing end dates in Humaans contract history will cause load failures that must be resolved manually before ingestion can succeed. |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
Schema-on-Write Validation Rejection
Officient enforces strict field formats, required fields, and relational constraints such as non-overlapping contract dates at ingestion time, meaning data that was stored flexibly across Humaans's decomposed objects will be rejected unless cleaned and restructured during transformation.
Compensation History Flattening
Humaans stores compensation as a separate resource with full effective dating across salary, bonus, equity, and commission types, while Officient only exposes a current wage plus monthly components, making historical compensation timelines difficult or impossible to fully preserve.
Time-Off Hierarchy Collapse
Humaans organizes time off in a five-layer hierarchy of Types, Policies, Allocations, Periods, and Entries/Adjustments, whereas Officient uses a simpler type-based Days Off structure, requiring significant flattening and potential loss of granular allocation and adjustment history.
Custom Field Pre-Creation Requirement
Officient requires all custom field definitions to be created before any custom values can be loaded, whereas Humaans treats custom fields as first-class API citizens that can be created and populated in any order, adding a mandatory sequencing dependency to the transformation pipeline.
National ID Format Validation
Humaans stores national tax IDs as free-text strings with no format enforcement, but Officient validates Belgian NISS/INSZ numbers against an 11-digit modulo-97 checksum, meaning any employees without properly formatted Belgian national IDs will fail ingestion.
API Rate Limit Throttling
Officient enforces a rate limit of 30 requests per 5 seconds compared to Humaans's 400 requests per minute, requiring careful batching and retry logic when loading large employee populations with multiple related records per person.
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
Can I export data directly from Humaans to Officient?
No. There is no native export-to-Officient feature in Humaans. You must extract data via Humaans's REST API or Data Exports API, transform it to match Officient's schema, and load it via the Officient API or manual import.
What is Officient's API rate limit for data migration?
Officient allows a maximum of 30 API requests per 5 seconds. Exceeding this returns a 429 status with no Retry-After header, so you must implement your own backoff. For a 500-employee migration with related data, expect the load phase to take 30+ minutes at minimum.
Does compensation history transfer from Humaans to Officient?
Not automatically. Humaans stores every salary change as a separate effective-dated Compensation object. Officient uses a current-wage model. You can migrate the current compensation directly, but historical changes must be archived separately or discarded.
How do I handle custom fields during the migration?
Humaans supports 7 custom field types including multiSelect and person references. Officient supports fewer types (text, number, date, money, email, select_option). You must audit all custom fields, recreate compatible ones in Officient before migration, and flatten unsupported types to text or archive them.
How do I preserve signed contracts when moving to Officient?
Officient's contract API supports a presigned_pdf parameter. Historical signed employment agreements should be loaded as presigned_pdf rather than re-sent for signature. Treat signed contracts as a separate workstream from the core employee data migration.