Employee sync and the employee API

Keep your employees in step with the other software you use (payroll, ERP, an older HR system). 9bx can read your people from that software's API on a schedule or when you press Sync now, your software can add and change employees in 9bx through the API, and 9bx can tell your software the moment someone joins, changes, moves or leaves.

Contents: Who can use it · Three ways to connect · Read employees from another system · Their API format · Field mapping and matching · Preview before you sync · Schedule and Sync now · Sync log · Leavers and deactivation · Add and change employees through the API · Employee webhooks · Example · FAQ

Who can use it

Every plan has employee sync, the employee API and webhooks.

• Connections: staff with the Developer API permissions under Employees: list connections and activity, set up and change connections, create API keys, and run sync and fix errors.
• API keys and webhooks: the same people as on Integrations and API.

Where: HR → Developer API (in the HR setup group) for connections. API keys and webhooks are under HR → Integrations.

Three ways to connect

Way	Direction	Use it when
Read their API	9bx reads employees from your other software, every hour, every day or when you press Sync now	Your payroll or ERP is the master list of people
They send to 9bx	Your software sends each employee to the connection's webhook address the moment it changes	Your developer can add a call to your software
Employee API	Your software adds, changes, deactivates and reactivates employees with an API key	You build your own integration, or use Zapier or Make

One connection can both read their API and take what they send. Nothing is ever deleted by any of them.

Read employees from another system

1. Open Developer API → New connection and give it a name, for example "Payroll system".
2. Under API, turn on reading and fill in:
   • Base address of their API, for example https://payroll.example.com/api. It must start with https://.
   • Sign-in: none, a bearer token, a user name and password, an API key in a header (you choose the header name, for example X-Api-Key), a key in the address, or a client ID and secret.
   • Paging: how their API splits long lists (see the next section).
3. Click Test connection. 9bx reads a few records and shows them, with every field it found. This list is what you map in the next step.
4. Choose the role new people's logins get, and the branch new people go to when the record names none.
5. Map the fields, click Preview, then Sync now.

Passwords, tokens and keys are stored encrypted. You can replace them but never see them again, and they never appear in logs or error messages.

Their API format

If their software was built to the 9bx format, leave everything as it is. For any other JSON API, open Their API format and say how it answers:

Setting	What it means	Example
Path	Where the list of people is, after the base address. / means the base address itself	v2/staff
List key	Where the list is inside the answer. . means the answer itself is the list	results
ID field	The field that identifies a person in their system	id
Change date field	The field with the date the person last changed	modified
No change date	Tick when their API has none. Every sync then reads everyone, and people who did not change are skipped
Deleted field	A yes/no field saying the person was deleted there	is_deleted
Paging	Cursor (the answer gives the next cursor), Page (page 1, 2, 3...), Offset (skip 0, 100, 200...) or None (one answer has everyone)	Offset
Parameter names	The names their API uses for the page, offset, cursor, page size and "changed since"	skip, take

A field inside another one is written with dots, for example job.department.name.

Field mapping and matching

Field mapping says where each of their fields goes: first name, last name or full name, work email (their login), phone, employee code, joining date, department, designation, branch, legal entity, grade, cost center, manager (by employee code), worker type, status, personal details, profile lists (addresses, bank accounts, identifiers and so on) and your custom fields. Choose Ignore for fields you do not want. A value map translates their words into 9bx's, for example their status "Left" to "inactive", and a date format reads dates such as 31/12/2026.

Matching decides which existing employee a record is, the first time it arrives. Choose any of employee code, email and identifier (for example a national ID number). After the first match the two stay linked. If two employees could match, nothing is guessed: the record waits in Errors for you to link it by hand.

Departments, branches and the like are looked up by code or name. A name 9bx does not know is left as it was and noted as a warning. Translation tables let you point their branch or legal entity names at yours.

Preview before you sync

Click Preview on the connection. 9bx reads the first records (25 by default, up to 100) and shows, for each person, what a sync would do, without changing anything:

• Create: a new employee, with the values that would be set.
• Update: an existing employee, with each field that would change, from and to.
• Skip: nothing to do (unchanged, older than what 9bx has, or a deletion the connection ignores).
• Deactivate: the record says the person was deleted and the connection deactivates on delete.
• Error: the record cannot be used, with the reason (for example no email, an email that already belongs to someone else, no role chosen for new people).

Personal details such as national ID or bank numbers show only that they would change, as ***.

Schedule and Sync now

• Schedule: every 15 minutes, 30 minutes, hour, 6 hours or day. The schedule starts after the first sync has been run by hand.
• Sync now reads what changed since the last sync. Full sync reads everyone again; people who did not change are skipped, so it is always safe.
• A sync that is already running is not started twice. Large first imports run in the background in parts.
• After five failed syncs in a row the connection stops reading and the person who created it gets an email. Fix the settings and turn it back on.

Sync log

The connection's Activity tab lists every sync: when it ran, what started it, and how many people were created, updated, skipped, deactivated and failed. Click a sync to see every record in it: their ID, the 9bx employee it became, and the result, with the reason for each failure. Filter by result to see only the failures. The record log is kept for 90 days.

Records that failed also wait under Errors, where you can Retry them after fixing the cause, Link them to the right employee, or mark them resolved.

Leavers and deactivation

9bx never deletes an employee because of a sync. Payroll, leave and audit history stay. What happens to leavers is your choice, and both are off on a new connection:

• Deactivate when they delete someone: when their system reports a person as deleted, the employee becomes inactive and their login stops working.
• Deactivate people no longer in their system: after each full read, employees linked to this connection who were not in it become inactive. With this on, every scheduled sync reads everyone.

Safety: nobody is deactivated after a sync that had errors or found nobody. If more than half of the linked people are suddenly missing, 9bx deactivates nobody and records the reason under Errors, because that usually means a wrong filter rather than half the company leaving.

A person who appears again later is made active again.

Add and change employees through the API

On Integrations → API keys, tick Add employees, change them, deactivate and reactivate them when you create a key. With it, your software can:

• add an employee with their login (the person gets the "set your password" email unless you turn it off), choosing one of the roles the API lists (never an owner or admin role);
• change an employee, sending only the fields that change;
• deactivate or reactivate an employee. There is no delete.

The key works as the person who made it: it can add and change employees only if that person may, only in that person's branches (and only the key's branch when the key has one), and it cannot fill in personal details (identity, pay, bank and similar) that person may not edit. Each key has its own limit of requests per minute, and a retried "add" with the same idempotency key is not added twice. Every change is in the activity log, marked as made through the API.

The full list of fields and calls is in the live API description on the Integrations screen.

Employee webhooks

On Integrations → Webhooks you can subscribe to:

Event	Sent when
Employee added	someone is added (by hand, import, sync or API)
Employee changed	an open field changes, with the names of the fields
Status changed	someone becomes active or inactive
Employee left	someone becomes inactive, with the separation date
Employee reactivated	an inactive person is made active again
Employee transferred	someone moves to another branch, with both branches

Personal details never travel in a webhook. Zapier and Make offer the same events.

Example scenario

Your payroll software lists staff at https://payroll.example.com/api/v2/staff and answers {"results": [...], "count": 240}, 100 at a time with offset and limit. Each person has id, staff_no, full_name, mail, dept and modified.

1. Create a connection "Payroll", base address https://payroll.example.com/api, sign-in API key in a header X-Api-Key.
2. Their API format: path v2/staff, list key results, ID field id, change date modified, paging Offset.
3. Test connection, then map full_name → Full name, mail → Email, staff_no → Employee code, dept → Department.
4. Matching: employee code, then email. Role for new people: Staff. Default branch: Dhaka.
5. Preview: 200 updates, 38 creates, 2 errors ("no email"). Fix those two in payroll.
6. Sync now, then set the schedule to every day. Turn on Deactivate people no longer in their system if payroll is your master list.

Troubleshooting and FAQ

Test connection says the answer has no list. Check List key (use . when the answer is the list itself) and Path.

Every person shows "Update" on every sync. Their change date may change on every read, or the API has none: tick No change date.

New people fail with "Choose the role". Pick the role new employees get in the connection settings.

"Email already has a login". Someone in 9bx already signs in with that email but is not this employee. Fix the email, or link the record to the right employee under Errors.

Nobody was deactivated after a sync. The sync had errors, found nobody, or more than half the people were missing (see Errors).

Can it import from a CSV file or SFTP? Not through a connection. Use Data import for files.