# flow2act · Nutzerimport starten

Speichere das geprüfte Organigramm gemeinsam und stelle Einladungen in die Warteschlange.

Liefert HTTP 202 mit Import-ID und Personen-IDs. Ein aktiver Import pro Organisation; nach unklarem Ergebnis denselben Idempotency-Key wiederverwenden. Pflichtfelder: displayName, email sowie externalId oder ref. managerRef gilt innerhalb des Imports; managerExternalId kann auch eine bestehende aktive Person derselben Organisation referenzieren. Die Reihenfolge ist egal. personId kann ein vorhandenes Profil ausdrücklich auswählen. Fehlende Position, Einheit oder Führungskraft bleiben bei bestehenden Profilen erhalten. Explizites null entfernt die Einheit/Führungskraft. Admin-Rechte und Freigabegruppen werden nicht importiert.

Nutze in Live eine Administratorsitzung und in der Sandbox eine Administrator-/Entwicklersitzung. Integrationen benötigen einen Servicekonto-Schlüssel mit organization:write UND users:invite. Schlüssel dürfen nur Importe desselben Servicekontos lesen/wiederholen. Zugriffe werden während der Hintergrundverarbeitung erneut geprüft.

## POST /v1/organization/user-imports

Authentication: restricted integration key (scope: users:invite) or flow2act sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator oder Sandbox-Entwickler erforderlich. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- people (array, required): min items 1 · max items 100

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flow2act.com/v1/organization/user-imports" \
  -H "authorization: Bearer $FLOW2ACT_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-user-import-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "people": [
    {
      "ref": "ceo",
      "externalId": "employee-1",
      "displayName": "Alex Example",
      "email": "alex@example.com",
      "jobTitle": "CEO",
      "managerRef": null
    },
    {
      "ref": "lead",
      "externalId": "employee-2",
      "displayName": "Kim Example",
      "email": "kim@example.com",
      "jobTitle": "Team Lead",
      "managerRef": "ceo"
    }
  ]
}'
```

## Response excerpt

```json
{
  "id": "import-uuid",
  "status": "queued",
  "total": 2,
  "processed": 0
}
```

Source: /docs/create-user-import
Full schemas: /docs/openapi.json