> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.crehana.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.crehana.com/_mcp/server.

# Sincronizar usuarios

El caso más común de integración: tu sistema de RRHH es la fuente de verdad y
Crehana tiene que reflejar altas, bajas y cambios.

## El flujo

#### Resolvé primero la estructura

Áreas, cargos y categorías de cargo tienen que existir **antes** que los
usuarios: crear un usuario los exige. Listá lo que ya hay y creá lo que
falte.

#### Traé el estado actual

`GET /org/{slug}/users/user-organizations/` te da los usuarios que Crehana
ya conoce. Recorrelo con `limit` y `offset` — ver [Paginación](/documentacion/conceptos/paginacion).

#### Compará contra tu nómina

Usá el correo como clave de correlación. Es el único identificador que
existe en los dos sistemas antes de la primera sincronización.

#### Aplicá las diferencias

Altas con `POST /users/`, cambios con `POST /users/update_user/`, bajas con
`POST /users/{id}/deactivate/`.

#### Completá lo que va después

Jefe y campos personalizados sí se asignan una vez que el usuario existe.

## Primero: la estructura organizacional

Área, cargo y categoría de cargo **son obligatorios para crear un usuario**, así
que tienen que existir antes. Se crean una sola vez y después se reutilizan:

```
GET  /org/{slug}/organizations/areas/
GET  /org/{slug}/organizations/positions/
GET  /org/{slug}/organizations/position-categories/
```

Listá primero lo que ya existe para no duplicar; si falta algo, se crea con el
`POST` de la misma ruta. Guardá los ids: son los que vas a mandar en cada alta.

## Altas

`POST /users/` exige seis campos: los tres de identidad más los tres de
estructura.

```bash
curl -X POST https://www.crehana.com/api/v5/rest/org/acme/users/ \
  -H "Api-Key: $API_KEY" -H "Secret-Access: $SECRET_ACCESS" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Ana",
        "last_name": "Pérez",
        "email": "ana@acme.com",
        "area_level_1_id": 12,
        "position_id": 34,
        "position_category_id": 5
      }'
```

Hay más campos opcionales —sede, jefe por correo, documento, fechas de ingreso
y baja, teléfono— que podés mandar en el mismo request. Están todos en la
[API Reference](/api-reference).

Si el correo ya existe en la organización vas a recibir un `409`. Eso no es un
fallo de tu integración: es la respuesta correcta a un alta duplicada. Tratalo
como "ya estaba" y seguí.

## Bajas: desactivar, no borrar

La desactivación es reversible: `POST /users/reactivate-user/` devuelve al
usuario a estado activo conservando su historial de aprendizaje.

Para bajas masivas está `POST /users/deactivate/`, que recibe varios usuarios
en una sola llamada — es lo que conviene si sincronizás por lotes.

> **Note**
>
> `DELETE /users/{id}/` también desactiva al usuario: internamente usa la misma
> familia de mutaciones que `deactivate`. Si tu intención es dar de baja, usá los
> endpoints de `deactivate`, que dicen en el nombre lo que hacen.

## Jefe

El jefe se asigna aparte, después del alta, con
`POST /users/{centralized_user_id}/boss/`. Para quitarlo, `DELETE` sobre la
misma ruta.

## Campos personalizados

Para lo que no entra en el modelo estándar —legajo, centro de costo, país de
facturación— están los campos personalizados. Se definen a nivel organización
y después se les asigna valor por usuario:

```bash
curl -X POST https://www.crehana.com/api/v5/rest/org/acme/users/123/custom-fields/ \
  -H "Api-Key: $API_KEY" -H "Secret-Access: $SECRET_ACCESS" \
  -H "Content-Type: application/json" \
  -d '{"custom_fields": [{"id": 7, "value": "L-4821"}]}'
```

Los campos que no incluyas en el request conservan su valor. No hace falta
mandar todos cada vez.

## Recomendaciones

* **Sincronizá por diferencias, no por reemplazo.** Traer el estado y aplicar
  solo lo que cambió es más barato y no toca usuarios que no se modificaron.
* **Guardá el `id` de Crehana en tu sistema** después del alta. Correlacionar
  por correo funciona, pero si alguien cambia de correo perdés el vínculo.
* **Empezá por QA.** El mismo flujo contra `qa.creha.co` te deja probar una
  sincronización completa sin tocar datos reales.