# Flowg8 · Start user import

Atomically save the validated directory and queue invitations.

Returns HTTP 202 with a job ID and person IDs. One active import per organization; reuse the same Idempotency-Key after an uncertain response. Required fields: displayName, email and externalId or ref. managerRef resolves within this import; managerExternalId can also resolve an existing active person in the same organization. Order is irrelevant. personId may explicitly select an existing profile. Omitting jobTitle, unitId or manager fields preserves existing values. Explicit null clears a unit/manager. No administrators or approval grants are imported.

Use an administrator session in Live or an administrator/developer session in Sandbox. Integration access requires a service-account key with BOTH organization:write and users:invite. Keys can access/retry only imports owned by the same service account. Access is rechecked during background processing.

## POST /v1/organization/user-imports

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. 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.flowg8.io/v1/organization/user-imports" \
  -H "authorization: Bearer $FLOWG8_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