Create up to 500 end users in a single request. Each user in the batch is processed independently: a failure on one item does not roll back or block the others, so the call returns 200 with a per-item report even when some items fail. For each item the endpoint behaves like a get-or-create keyed on email within your client — a new user is created, or the existing user with that email is returned unchanged.

Authentication & access

• Requires a client API token: Authorization: Bearer <token>.
• The caller must hold the kyc.users.write permission and have the OWNER or OPERATIONS role.

Request body

Each item in users has:

Verification mode

Each user is assigned a verification mode that determines how its eligibility is later assessed:

• urbanpayx_kyc — the user is verified through UrbanpayX-managed identity verification.
• external_attestation — the user's verified status is supplied by you out of band and recorded against the user.

If a user with the same email already exists, the existing record is returned as-is. If you pass an explicit verification_mode that disagrees with the stored user's mode, that item fails (it does not silently switch); use PATCH /api/v1/kyc/users/USER_ID/verification-mode to change an existing user's mode.

Response

Returns 200 with a summary and a per-item result list:

• total — number of items submitted.
• succeeded — number of items processed successfully (created or returned existing).
• failed — number of items that failed.
• results — per-item results in submission order. Each entry contains index (zero-based position in the request), email, and success. On success, user holds the created or existing user record (id, email, full_name, kyc_status, verification_mode, external_verification_status, verification_source, created_at, message). On failure, error_code and error_message describe why that item failed while the rest of the batch still processes.

Error responses

These status codes apply to the request as a whole. Per-item problems are reported inside results (via error_code / error_message), not as HTTP errors.

Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.