> For the complete documentation index, see [llms.txt](https://help.steeple.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.steeple.com/en/administration/synchroniser-annuaire-api.md).

# How do I synchronize my Directory of collaborators with the Steeple API?

## Overview

The Steeple API lets you automatically populate your Steeple Directory from the tool your organization relies on for employee information: HRIS, company directory, payroll tool, internal database, and so on. All you need is for that tool to be able to generate an employee file and call the API, for example every night.

The API requires development work on your end. Steeple offers ready-to-use integrations for the most common sources: first check whether one of them suits your needs, and use the API only for cases they don't cover.

## Which solution should you choose to sync your directory?

| Your situation                                                                | Recommended solution                                                                                                                                                            |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You use Lucca as your HRIS                                                    | The Lucca connector: see [How do I sync my employee directory with Lucca?](https://help.steeple.com/en/administration/synchroniser-annuaire-lucca.md)                           |
| Your employees are managed in Microsoft Entra ID or Okta                      | SCIM provisioning, with SSO configured beforehand: see [Automatic employee provisioning (Provisioning / SCIM)](https://help.steeple.com/en/administration/provisioning-scim.md) |
| You update the directory occasionally, a few times a year                     | Import a file from Administration: see [How do I bulk import employees?](https://help.steeple.com/en/administration/import-collaborateurs.md)                                   |
| None of these solutions works for you, and you want automatic synchronization | The Steeple API, described in this article                                                                                                                                      |

These integrations are configured in**Administration**, under **Integrations** (`/administration/integrations`). Don't use multiple sources for the same directory: two sources writing to the same profiles will eventually conflict. The API doesn't prevent an import when another sync is active, so you need to check this yourself. If you're unsure, describe your needs in [Help and resources](https://app.steeple.com/help) to find the right solution.

The API works like the file import feature in Administration: you send an employee file, Steeple validates and then processes it, and you can review the import summary and any errors, including the relevant line.

## Prerequisites

* A Steeple API token: see [How do I use the Steeple API?](https://help.steeple.com/en/administration/api-steeple.md).
* An organization administrator account, under which imports are submitted.
* No other active directory sync (SCIM or Lucca).

## The administrator account

Each import call requires a `user_id` parameter: the ID of an organization administrator. The import is submitted under their name and appears in the import history as if they had uploaded it themselves.

To find this ID, call `GET /v1/users` : the list returns each employee's`id`, first name, and last name. Find the administrator by name and note their `id`.

We recommend using a dedicated administrator account for the integration: if the account is removed from the organization or loses its administrator permissions, imports will be rejected.

## Choose the import type

The `operation` parameter corresponds to the import types available in Administration.

| `operation`      | Import type             | New employees | Employees included in the file                             | Employees not included in the file                 |
| ---------------- | ----------------------- | ------------- | ---------------------------------------------------------- | -------------------------------------------------- |
| `INSERT`         | Insertion               | Created       | Unchanged                                                  | Unchanged                                          |
| `UPSERT`         | Insert and update       | Created       | Updated                                                    | Unchanged                                          |
| `MIRROR_LENIENT` | Mirror without deletion | Created       | Updated, and removed from communities absent from the file | Unchanged                                          |
| `MIRROR_STRICT`  | Mirror                  | Created       | Updated, and removed from communities absent from the file | **Removed from the organization, account deleted** |
| `DELETE`         | Deletion                | Skipped       | Removed from the organization                              | Unchanged                                          |

For regular synchronization, `UPSERT` or `MIRROR_LENIENT` are suitable in most cases: they do not remove anyone from the organization.

Do not use `MIRROR_STRICT` unless your file contains **all** the organization's employees. An incomplete file deletes the accounts of employees who are not listed in it.

## Prepare the file

The file is the same as for importing from Administration: start with the template you can download in the import wizard for the import type you selected. Accepted formats: CSV, `.xlsx`, `.xls`, `.xlsm`.

Columns are recognized by their exact labels, in your organization's language: use the labels in the column corresponding to that language, as shown in the template. Their order does not matter. Any unrecognized column is ignored and reported in the import messages.

| Content                                                 | French                        | English                       | Spanish                          | German                                   |
| ------------------------------------------------------- | ----------------------------- | ----------------------------- | -------------------------------- | ---------------------------------------- |
| Work email address                                      | `Email`                       | `Email`                       | `Correo electrónico`             | `Email`                                  |
| HR ID                                                   | `Matricule`                   | `Staff ID`                    | `Matrícula`                      | `Personalnummer`                         |
| Login ID, for an employee without an email address      | `Identifiant`                 | `Login`                       | `Identificador`                  | `Login`                                  |
| Last name (required)                                    | `Name`                        | `Last name`                   | `Apellido`                       | `Nachname`                               |
| First name (required)                                   | `First name`                  | `First name`                  | `Nombre`                         | `Vorname`                                |
| Phone number                                            | `Phone`                       | `Phone number`                | `Número de teléfono`             | `Telefon`                                |
| Birthday day and month, for example `31/12`             | `Birthday`                    | `Birthday`                    | `Día de cumpleaños`              | `Geburtstag`                             |
| Name of an existing community, one column per community | `Community 1`, `Community 2`… | `Community 1`, `Community 2`… | `Comunidad 1`, `Comunidad 2`…    | `Gruppe 1`, `Gruppe 2`…                  |
| Name of an organizational department                    | `Department`                  | `Department`                  | `Servicio`                       | `Abteilung`                              |
| Name of an organizational location                      | `Location`                    | `Location`                    | `Ubicación`                      | `Standort`                               |
| Job title                                               | `Position`                    | `Position`                    | `Puesto`                         | `Position`                               |
| Manager's email address                                 | `Manager's email`             | `Manager's email`             | `Correo del responsable`         | `Supervisor email`                       |
| Start date, for example `31/12/2026`                    | `Company start date`          | `Seniority date`              | `Fecha de entrada a la empresa`  | `Datum des Eintritts in das Unternehmen` |
| Contract end date, for example `31/12/2026`             | `Contract end`                | `Contract end date`           | `Fecha de fin de contrato`       | `Vertragsende`                           |
| Administration rights: `1` or `0`                       | `Administrator`               | `Administrator`               | `Administrador`                  | `Administrator`                          |
| Bio                                                     | `Bio`                         | `Biography`                   | `Biografía`                      | `Biografie`                              |
| SSO login: `1` or `0`                                   | `SSO login method`            | `SSO Login Method`            | `Método de inicio de sesión SSO` | `SSO-Anmeldemethode`                     |
| SSO identifier, if your organization uses SSO           | `SSO identifier`              | `SSO Identifier`              | `Identificador SSO`              | `SSO-Kennung`                            |
| 4-digit code                                            | `TV PIN code`                 | `TV PIN`                      | `PIN de TV`                      | `TV-PIN`                                 |

For yes/no columns, `1` and `0` are accepted regardless of language.

An employee is identified by their **email**, their **employee ID** or their **identifier**. Each row must contain at least one of these, and the same identifier cannot appear twice in the file. If all three change at the same time in your source system, the employee is treated as a new person.

The `DELETE` import uses only the three identification columns: email, employee ID, and login identifier.

## Start an import

### Step 1 — Declare the file

```bash
curl -X POST "https://api.steeple.com/v1/blobs?user_id=<id administrateur>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"blob": {"filename": "collaborateurs.csv", "content_type": "text/csv", "byte_size": 48213, "checksum": "<empreinte>"}}'
```

* `byte_size` : the file size in bytes.
* `checksum` : the file's MD5 checksum, encoded in base64. For example: `openssl md5 -binary collaborateurs.csv | base64`.

The response contains a `signed_id` key and a `direct_upload` block, with the upload URL (`url_for_direct_upload`) and the headers to send (`headers_for_direct_upload`). The upload URL is valid for 5 minutes.

### Step 2 — Upload the file

Send the file contents to the `direct_upload.url_for_direct_upload` URL, with all the headers from `direct_upload.headers_for_direct_upload`. This request does not include the Steeple token.

```bash
curl -X PUT "<url_for_direct_upload>" \
  -H "Content-Type: text/csv" \
  -H "Content-MD5: <empreinte>" \
  -H "Content-Disposition: <valeur reçue>" \
  --data-binary @collaborateurs.csv
```

### Step 3 — Start the import

```bash
curl -X POST "https://api.steeple.com/v1/member_provisionings" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "<id administrateur>", "signed_id": "<signed_id>", "operation": "UPSERT", "dry_run": false, "notify_users": false}'
```

* `dry_run` : `true` to run a simulation (see below). `false` by default.
* `notify_users` : `true` to send an account activation email to newly created employees. `false` by default: you can send the login credentials later from Administration (see [How do I send login credentials?](https://help.steeple.com/en/administration/envoyer-identifiants.md)).

The response contains the import`id` .

### Step 4 — Track the import

The import is processed in the background. Poll its status until it is complete:

```bash
curl "https://api.steeple.com/v1/member_provisionings/<id>?user_id=<id administrateur>" \
  -H "Authorization: Bearer <token>"
```

The field `state` goes through `created`, `loading`, `checking`, then `syncing`. The import ends with `succeeded`, `failed` or `canceled`.

### Step 5 — Check the result

* `GET /v1/member_provisionings/{id}/reports` : the import summary, with totals by operation and community (for example, `CREATE_MEMBER` : 2 employees created in the “Head Office” community). Add `dry_run=true` to display only the summary for a simulation.
* `GET /v1/member_provisionings/{id}/messages` : errors and warnings, with the relevant row and column.

Both lists require the `user_id`parameter. Request `per_page=50` (the maximum). If an import generates more than 50 messages, view the full report on the Administration **Import** page, which also shows imports launched through the API.

An error detected while validating the file (missing name, row without an identifier, duplicate identifier, etc.) causes the entire import to fail before any changes are made: correct the file and run the import again. Also check the messages for an import that `succeeded`, as it may contain warnings.

## Simulation

With `dry_run: true`, Steeple calculates what the import would change without applying anything. The import stops at the `reviewing`state. An administrator reviews the report and approves the import from the Administration **Import** page. The API does not allow a simulation to be approved.

Run your first imports in simulation mode, and always run a `MIRROR_STRICT`import. Without simulation, an import `MIRROR_STRICT` is applied directly: the confirmation requested in Administration before deleting a large number of accounts does not apply.

Simulation is **required** for a file that assigns or changes a login identifier. Without simulation, the import fails with the message `dry_run_required`.

## What the assistant can do

The assistant cannot launch an import via the API. It must first direct users to the integration best suited to their needs (Lucca connector, SCIM provisioning, file import) and present the API only as a last resort. It can then explain how API synchronization works, the import types and file format, and direct users to the **Integrations** page to generate a token or to the **Import** page to validate a simulation. For details on the endpoints, direct users to <https://api-docs.steeple.com>.
