By default, Zai Payments requires every user on your platform to have a unique email address. If you try to create or update a user with an email address that's already registered, the API returns a 422 Unprocessable Entity error.
This article explains why the error occurs, how to find the user who already holds the email address, and what your options are.
Why this happens
Zai enforces a unique email constraint for each platform. You'll see this error in two situations.
1. Creating a new user with an email address that's already registered on your platform.
POST https://test.api.promisepay.com/users (Pre-live)
POST https://secure.api.promisepay.com/users (Live)
Response:
422 Unprocessable Entity
{"errors":{"email":["already exists"]}}
2. Updating an existing user with an email address that's already assigned to a different user.
PATCH https://test.api.promisepay.com/users/:id (Pre-live)
PATCH https://secure.api.promisepay.com/users/:id (Live)
Response:
422 Unprocessable Entity
{"errors":{"email":["already exists"]}}
Email addresses aren't case-sensitive, so Jane@example.com and jane@example.com are treated as the same address.
Step 1: Find the user who holds the email address
Before you take any action, confirm which user account the email address belongs to. You can do this in the Zai Dashboard or through the API.
Option A: Search in the Zai Dashboard
- Log in to the Zai Dashboard at dashboard.hellozai.com and select Pre-live or Live.
- Go to Users and enter the email address in the search bar.
- The matching user appears in the results, along with their user ID, name, and account status.
Option B: Search using the API
Use the List Users endpoint with the search query parameter, passing the email address as the search value.
GET https://test.api.promisepay.com/users?search={email_address} (Pre-live)
GET https://secure.api.promisepay.com/users?search={email_address} (Live)
For example:
GET https://secure.api.promisepay.com/users?search=example%40yourdomain.com
Because search is a general text search, it may return more than one user. Check that the email field in the result exactly matches the address you're looking for. The id field of that result is the Zai user ID of the account that already holds the email address.
Step 2: Choose the right course of action
Once you've identified the existing user, find the scenario below that matches your situation.
| Scenario | What to do |
|---|---|
| The existing user is the same person you're trying to create | Use the existing user ID for your transaction. You don't need to create a new user. |
| The existing user is a duplicate created in error | Update your own records to reference the correct user ID. If the duplicate holds wallet funds, bank accounts, or transaction history, contact Zai Support before taking further action. |
| The email address belongs to an old or outdated user record, and you want to reuse it for a new user | First update the existing user's email address to a different, unique address using PATCH /users/:id. You must include the user's first_name in the request, as it's a required field. You can then create the new user with the original address. |
| Your platform genuinely needs multiple users to share the same email address | See Enabling shared email addresses below. |
Enabling shared email addresses (optional)
If your platform needs multiple users to share an email address, email support@zaipayments.com with a short description of your use case and which environments you need it in (Pre-live, Live, or both). We'll review your request and let you know if we approve enabling this for your platform.
Note: Enabling this feature removes the uniqueness check entirely for your platform. Once it's enabled, the API will accept any email address when creating or updating users, even if it's already in use. You'll be responsible for managing duplicate detection within your own system.
Related articles
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article