> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/nhi/csv-synchronization.md).

# Synchronize from a data source

Load and enrich many non-human identities from a data source using OpenIAM's synchronization engine, with Non-Human Identity as the object type.

## What this is, and when you need it

Non-human identities (NHIs) are a first-class object type in OpenIAM's existing **synchronization** engine, so you can create and keep them up to date in bulk from a data source — a comma-separated-values (CSV) file, a database view, or any source a synchronization configuration can read. Use this when you are onboarding an estate of service accounts, keys or workloads, or reconciling the inventory against an external register of truth, rather than registering each identity by hand.

This is the same synchronization mechanism used for users and roles; you point a configuration at your source and choose **Non-Human Identity** as its object type. To register a single identity, use [Register a non-human identity](/administration-guide/nhi/register-an-nhi.md) instead.

{% hint style="warning" %}
This is **not** the **Import / Bulk Enrich** button on the inventory page. That button is a placeholder for a future discovery-and-enrichment feature and does nothing yet. Bulk loading today is done through a synchronization configuration, described below.
{% endhint %}

## Before you begin

* A data source your synchronization configuration can read, with one row per non-human identity. At a minimum each row needs a **name** and a **type**; include owner, environment, expiry, purpose, credentials and a requested status where you have them.
* The right to create and run synchronization configurations in the Webconsole.
* An understanding of [what an NHI needs to activate](/administration-guide/nhi/lifecycle.md#activation-requirements) — a row that asks for an Active identity must supply everything activation requires, or it stays a Draft.

## Configure the synchronization

Create a synchronization configuration the usual way (see the provisioning and synchronization guides under [Connect applications and automate lifecycle](/administration-guide/lifecycle.md)), and set its **object type** to **Non-Human Identity**. What the NHI processor does with each row:

{% stepper %}
{% step %}
**Match.** Each source row is matched to an existing identity by name (case-insensitive, exact). No match means a new identity is created.
{% endstep %}

{% step %}
**Save the identity.** The row's fields are written to the identity. New identities are created as **Draft**.
{% endstep %}

{% step %}
**Save credentials.** Credential rows are written idempotently — a re-sync updates a credential in place rather than adding a duplicate.
{% endstep %}

{% step %}
**Activate, if requested.** A row that asks for an Active status is activated, provided it meets the [activation requirements](/administration-guide/nhi/lifecycle.md#activation-requirements); if activation is refused, the identity is left as a Draft and the run logs a warning. An already-Active match is left alone, so re-running the sync is safe.
{% endstep %}

{% step %}
**Handle orphans, if enabled.** With orphan detection on, an existing identity that no longer appears in the source is **decommissioned** — preserving its history — rather than deleted (a Draft with no source may be removed).
{% endstep %}
{% endstepper %}

## Verification

After the run, open the [inventory](/administration-guide/nhi/inventory.md) and confirm the identities appear with the expected type, owner and status. Rows that could not activate show as **Draft** — check the synchronization run log for the warning that says why (usually a missing owner, expiry or backup owner). Re-running the same source should report updates, not duplicates.

## When it goes wrong

| Symptom                                                            | Likely cause                                                                                                                 |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Identities import but stay Draft when the source asked for Active. | The rows do not meet the activation requirements — owner, expiry, related human or backup owner. Fill the source and re-run. |
| Credentials appear twice after a re-sync.                          | The credential rows are not matching to the same identity — check the match field so re-syncs land on the existing record.   |
| An identity that left the source is still Active.                  | Orphan detection is off. Turn it on to have departed identities decommissioned automatically.                                |
| The **Import / Bulk Enrich** button does nothing.                  | It is an unwired placeholder. Use a synchronization configuration, as described here.                                        |

## Related

* [Register a non-human identity](/administration-guide/nhi/register-an-nhi.md) — the by-hand alternative.
* [Lifecycle and status](/administration-guide/nhi/lifecycle.md) — why a row may import as a Draft.
* [Connect applications and automate lifecycle](/administration-guide/lifecycle.md) — how synchronization configurations are built and run.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/administration-guide/nhi/csv-synchronization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.