Bulk upsert users
POST/v1/users
Bulk-upsert users. Upsert key: login_account. Plain-text passwords are hashed by the API before storage; if you omit the password field, the existing hash is preserved. When you supply a password, must_change_password is set to true so the user is forced to rotate it on first sign-in.
Group memberships use the same groups shape returned by GET — an array of { external_code } objects. Any name field sent is ignored. Replace-all semantics — the array on POST fully defines the user's memberships after the call. Omit the field entirely to leave memberships untouched. Send [] to clear all memberships. Codes that don't match any user_groups.external_code return 400 with the offending list.
Email is UNIQUE per tenant. If a payload's email conflicts with a different existing login_account, the call returns 409 with details before any write happens.
Required fields: first_name, last_name, email, login_account, login_type. login_type=2 (SSO) additionally requires sso_provider (the alias from idp_sso_config).
No full_load: bulk replacement is deliberately not supported. To kill stale users automatically, use POST /users/deactivate-inactive.
Max 1000 users per request.
Unknown fields (e.g. sso_subject) are silently ignored.
Request
Responses
- 200
- 400
- 401
- 403
- 409
- 500
Users upserted successfully
Validation error or unknown group external_codes
Unauthorized
Forbidden — insufficient permissions (POST_USER or POST_DATA required)
Email conflict with existing row under a different login_account
Internal server error