Create (or retrieve) an end user under the authenticated client for identity-verification tracking. The user's email is matched case-insensitively: if a user with the same email already exists for your client, the existing record is returned unchanged; otherwise a new user is created with no verification yet. Returns the user record and a message indicating whether it was created or already existed.

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

Create vs. retrieve

• New email — a user is created with kyc_status = none, external_verification_status = pending, and verification_source = none. The response message is User created successfully.
• Existing email — the stored record is returned as-is and message is User already exists. This call never mutates an existing user.
• Mode conflict — if you pass verification_mode explicitly and it differs from the existing user's mode, the request is rejected with 409. Use PATCH /api/v1/kyc/users/USER_ID/verification-mode to change the mode of an existing user.

Response

200 — returns the user record:

• id — unique user ID.
• email, full_name.
• kyc_status — one of none, pending, approved, rejected, on_hold.
• verification_mode — the mode assigned to this user.
• external_verification_status — pending, verified, or rejected (relevant in external-attestation mode).
• verification_source — none, urbanpayx, or external.
• created_at — creation timestamp.
• message — User created successfully or User already exists.

Error responses

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