This guide covers how employment terms affect existing integrations, the API, table uploads, webhooks, and includes how Humaans keeps People fields in sync.
For answers to common questions about effective dates, contract types, reporting, and workflows, visit Employment terms FAQ.
Do I need to update my existing integrations?
No. Moving contract type and place of work into employment terms doesn't require changes to existing API connections, integrations, or data warehouse connections that use the existing fields. You can keep your current setup and adopt dated records when you need them.
Which existing API fields remain available?
Existing integrations can continue to read these fields on /api/people:
contractType
locationId
remoteCity
remoteRegionCode
remoteCountryCode
remoteTimezone
Humaans keeps these fields aligned with the person's current employment terms.
Can I manage effective-dated changes through the API?
Yes. The Employment terms API supports creating records and managing their effective dates, following the same general approach as job roles and compensation. This lets an integration schedule future changes and read past ones.
To learn more, visit the Humaans API documentation.
What happens if I write the existing fields through the API?
Writing contractType, locationId, or the remote* fields on /api/people records a change that takes effect today. For people who haven't started yet, it takes effect on their employment start date. To change past or upcoming values, use the Employment terms API.
What does my integration receive before a future change takes effect?
The existing People fields represent the person's current terms. For example, if someone is scheduled to move offices next month, the People API returns their current office until the change takes effect. The future-dated record is available through the Employment terms API, and Humaans updates the People fields when it takes effect.
How does the sync between terms and People fields work?
When a terms change affects someone's current contract type or place of work, Humaans writes the matching values to their People record. Humaans updates only the fields whose values differ.
A daily reconciliation also compares the stored People fields with the terms in effect that day. It handles:
Backfill: Bringing existing People records into line with their current terms.
Scheduled changes: Updating People fields when future-dated terms take effect.
Reconciliation brings current values into line. It doesn't recreate a history of changes that were never recorded.
Renaming a contract type also queues a reconciliation, because contractType on the People record stores the contract type's name.
Can the sync trigger webhooks and integration updates?
Yes. The sync uses the standard People update process. When values change, it can create audit events, send webhooks, and trigger the usual downstream integration activity. Connected systems can receive updates when out-of-sync values are reconciled or when scheduled terms take effect.
Do my existing table uploads still work?
Yes. You can keep using your existing table upload process. You can also:
Include Employment type, which is optional in uploads.
Specify an effective date to schedule a change, such as an office move next month.
Leave the effective date empty to use the current date.
To learn more, visit Employment terms history table.
Will new fields be available through my ATS integration?
Support for existing fields continues, but new fields can need additional integration support. Before you rely on employment type flowing from your ATS into Humaans, check availability for your integration.
Does moving a custom field into Terms update my integrations?
No. The compatibility sync covers the standard contract type and place of work fields only. It doesn't extend to custom fields. The original field and the Terms field don't synchronise, and the field reference or mapping can change, so remap any connected integrations.
To learn more, visit Manage custom fields.