---
name: buk-onboard-and-terminate-employees
description: Create an employee in Buk with their job, pension plan and documents, and run the termination (finiquito) flow — including how to undo one.
api: buk:data-access-api
generated: '2026-08-08'
method: generated
source: openapi/buk-data-access-api-chile-openapi.yml
operations:
- POST /employees
- PATCH /employees/{id}
- POST /employees/{id}/clone
- POST /employees/{id}/jobs
- PATCH /employees/{employee_id}/jobs/{id}
- PATCH /employees/{employee_id}/jobs/{job_id}/cost_centers
- POST /employees/{id}/plans
- PATCH /employees/{employee_id}/plans/{id}
- POST /employees/{id}/docs
- GET /employees/{id}/docs
- PUT /docs/{id}/signatures
- POST /docs/{id}/signatures/process
- GET /jobs/{id}/termination
- POST /jobs/{id}/termination
- PATCH /jobs/{id}/terminate
- PATCH /jobs/{id}/undo_terminate
- POST /jobs/{id}/undo
- GET /jobs/events/hires
- GET /jobs/events/terminations
- GET /jobs/events/movements
- GET /workflow/alta/processes
---

# Onboard and terminate employees in Buk

This is the write path into a payroll system of record. Everything here has legal and financial
consequence in the country the tenant runs in. Treat it accordingly.

## Auth and scope

`auth_token` header, and the token must carry **Lectura y Modificación** on Employee and Job.
Every operation's description in the contract names the entity permission it needs — read it
before you assume a read token will do.

## Onboarding

1. **Create the person.** `POST /employees`. If you do not send `active: true` the record is
   created **inactive**. `code_sheet` is optional and will be autogenerated when omitted and the
   person does not already exist. `POST /employees/{id}/clone` copies an existing record when
   you are creating a near-duplicate.
2. **Create the job.** `POST /employees/{id}/jobs`. The employee record is not the employment
   contract — the job is. Contract type, dates, salary and cost centre live here.
3. **Assign cost centres.** `PATCH /employees/{employee_id}/jobs/{job_id}/cost_centers`.
4. **Set the pension/social-security plan.** `POST /employees/{id}/plans`, and
   `PATCH /employees/{employee_id}/plans/{id}` to correct it. This is the most
   country-specific part of the model — the definition set differs across the Chile, Colombia,
   Peru, Mexico and Brazil contracts.
5. **Attach documents for signature.** `POST /employees/{id}/docs`, then
   `PUT /docs/{id}/signatures` to set the signature configuration and
   `POST /docs/{id}/signatures/process` to start the signing process. Confirm with
   `GET /employees/{id}/docs`.
6. `GET /workflow/alta/processes` reports the tenant's onboarding (alta) workflow processes if
   the tenant runs them.

## Termination (finiquito)

1. `GET /jobs/{id}/termination` first — read the computed termination before you commit it.
2. `POST /jobs/{id}/termination` creates the termination record.
3. `PATCH /jobs/{id}/terminate` executes the termination on the job.
4. **Reversal exists and you should know it before you need it.**
   `PATCH /jobs/{id}/undo_terminate` reverses a termination; `POST /jobs/{id}/undo` reverses a
   job movement. Do not build a compensating write of your own.

## Audit

`GET /jobs/events/hires`, `GET /jobs/events/terminations` and `GET /jobs/events/movements`
give the event streams for a period — use these to reconcile what you believe you wrote against
what Buk recorded.

## Rules you must respect

- **There is no idempotency mechanism.** No `Idempotency-Key`, no dedupe key, nothing. A retried
  `POST /employees` creates a second person. Before retrying any write, re-read
  (`GET /employees` filtered by `email` or `document_number`) and only retry when the record is
  genuinely absent. Hold your own request ledger.
- **409 means concurrent modification**, not conflict-with-your-payload — the contract documents
  "Records are being updated concurrently." Back off and re-read.
- **`job_movement` fires on any save.** Saving the job form with no changes still emits the
  webhook. Do not treat a `job_movement` event as proof something changed; diff the record.
- **Errors are free text.** No machine-readable code exists. See `errors/buk-problem-types.yml`.
- **No 429 is documented.** Serialise bulk onboarding rather than fanning it out.