Skip to main content
Creating an employee writes a person into the customer’s HRIS. The connector defines what that write accepts, so the schema comes first. Nothing in Bindbee removes the record once it lands.
Before you start
  • You’ve confirmed the integration supports this write - see Check write support.
  • You can generate a stable idempotency key per person - see Idempotency.

​
Steps

1

Fetch the schema

Employee creation differs by platform and by tenant, so read the field list from the schema rather than hardcoding it.The response is JSON Schema with Bindbee’s own isRequired and enumInformation keywords on top - see Meta APIs.Result: The contract for this integration.
2

Assemble the body from the schema

Work through the required array on the root object, then on each nested object you include.
A nested object that’s optional at the top level still enforces its own required fields once you send it. So a partial address fails validation where omitting it entirely would pass.Result: A body conforming to the schema.
3

Add integration-specific values if the schema asks for them

The Meta response defines whether this connector expects integration_params or additional_attributes, and what belongs in each - see Integration-specific fields.Where it does, the values reference configuration that already exists in the customer’s HRIS, such as an employment type ID, a pay group or a legal entity.Result: The platform-specific values this connector needs.
4

Send with an idempotency key

Derive the key from your own record for this person, so a retry reuses it - see Idempotency. A new key on retry is a new creation request.
Result: The employee is created upstream.
5

Match the record after the next sync

The write confirms the create without returning the Bindbee id. The employee reaches your reads on the next sync - see Syncing.Find them by a stable upstream identifier such as work_email or employee_number, then store the Bindbee id from that read. Key your own record on the id, since source systems reissue employee numbers and remote_id values on rehire or transfer - see Reading employees.Result: Your record linked to a stable Bindbee id.
A rehire or transfer is a new employment rather than a new employee, and creating one duplicates the person - see Reading employees.

​
Frequently Asked Questions

The retry carried a different X-Idempotency-Key, so Bindbee read it as a new creation - see Idempotency.There is no delete endpoint for employees, so the duplicate has to be merged or removed in the customer’s HRIS.
The credentials are valid but don’t permit the operation. Check the connector token belongs to this API category, and that writes are enabled on the model.Where both hold, the source system is refusing the write itself, which is a permission to fix in the customer’s HRIS - see Origin-system errors.