Update user email

Use this API to update the email address for an existing user.

Important Note: The user's email can be updated at any time, even if they have active cases.

HTTP Request

POST <BASE_URL>/api/v1/users

Headers

Header	Type	Description
cv-api-key	string	Required. Your unique API key for authentication.
Content-Type	string	Required. Must be application/json.

Request Body

The request body is a JSON object with two top-level fields: action and data.

Field	Type	Description
action	string	Required. The action to be performed. This should always be UPDATE_EMAIL.
data	object	An object containing the current and new email addresses.

updateEmail Object

Field	Type	Description
currentEmail	string	Required. The user's current email address.
newEmail	string	Required. The new email address for the user.

Example Request

curl --location '<BASE_URL>/api/v1/users' \
--header 'cv-api-key: <redacted>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "UPDATE_EMAIL",
    "data": {
        "currentEmail": "john.doe@carevalidate.com",
        "newEmail": "doe.john@carevalidate.com"
    }
}'

Responses

Success Response

A successful request returns a 200 status code and a JSON object confirming the email update.

Response

{
    "status": 200,
    "success": true,
    "message": "Email updated successfully",
    "data": {
      "user": {
        "email": "doe.john@carevalidate.com",
        "firstName": "John",
        "lastName": "Doe",
        "dob": "2000-10-01",
        "phoneNumber": "+11111111111",
        "gender": "MALE",
        "address": "1 ABC St",
        "address2": "Apt 3",
        "city": "NYC",
        "state": "NY",
        "country": "US",
        "postalCode": "10101"
      }
    }
}

Failure Responses

A request can fail for several reasons, returning an error status code and a JSON object with a descriptive message.

User does not exist

If the currentEmail provided in the request body doesn't match an existing user, the API will return this response.

{
  "status": 400,
  "success": false,
  "message": "User {currentEmail} does not exist"
}

User does not exist in the organization

If the user exists but is not part of the organization associated with the API key, the API will return this response.

{
  "status": 400,
  "success": false,
  "message": "User {currentEmail} does not exist in the organization"
}

Not allowed to update the email

If the user's role is not USER, they are not permitted to update their own email, and this response will be returned.

{
  "status": 400,
  "success": false,
  "message": "Not allowed to update the email"
}

New email already exists

If the newEmail provided in the request is already associated with another user, the API will return a conflict error.

{
  "status": 400,
  "success": false,
  "message": "New Email {newEmail} already exists"
}

New Email already exists in database

This response occurs when the new email you're trying to set is already associated with an existing user in the database, and that user has a different ID. This prevents one user from taking another user's email.

{
  "status": 400,
  "success": false,
  "message": "User with email {newEmail} already exists in database"
}

New Email already exists in authentication service

Similar to the above, this response is triggered if the new email is already linked to a different user account within the authentication system. This ensures the uniqueness of email addresses across all user accounts.

{
  "status": 400,
  "success": false,
  "message": "User with email {newEmail} already exists in authentication"
}