Check if user already exists

This API checks if a user exists in the system by their email or phone number. It's useful for determining if you need to create a new user or if one already exists.

Note: Either email or phone number must be provided. If both are provided, email takes priority. Special characters in email and phone-number must be url-encoded. For example, pass "%2b" instead of "+" in the phone number.

HTTP Request

GET <BASE_URL>/api/v1/check-user

Headers

Header	Type	Description
cv-api-key	string	Required. Your unique API key for authentication.

Query Parameters

Parameter	Type	Description
email	string	The user's email address. Required if phone-number is not provided.
phone-number	string	The user's phone number. Required if email is not provided.

Note: You must provide at least one of the query parameters (email or phone-number). If both are provided, email takes priority.

Example Request

curl --location '<BASE_URL>/api/v1/check-user?email=john@example.com&phone-number=%2b11111111111' \
--header 'cv-api-key: <redacted>'

---

Responses

Success Responses (User Found)

A successful request returns a 200 status code with information about the user.

User exists with the provided email:

This response is returned if a user is found with the provided email.

{
  "status": 200,
  "success": true,
  "message": "Email already exists",
  "data": {
    "createdAt": "2024-09-04T12:00:00.000Z",
    "existsInCurrentOrganization": true,
    "code": "EMAIL_EXISTS"
  }
}

User exists with the provided phone number:

This response is returned if a user is found with the provided phone-number.

{
  "status": 200,
  "success": true,
  "message": "Phone number already exists",
  "data": {
    "createdAt": "2024-09-04T12:00:00.000Z",
    "existsInCurrentOrganization": false,
    "code": "PHONE_NUMBER_EXISTS"
  }
}

Note: The existsInCurrentOrganization field will be true if the user belongs to the organization associated with the cv-api-key, and false otherwise.

Success Response (User Not Found)

If the user is not found, the API returns a 200 status code with a success flag set to false.

{
  "status": 200,
  "success": false,
  "message": "User does not exist",
  "data": {
    "code": "USER_NOT_FOUND"
  }
}

Failure Responses

A request can fail for several reasons, returning a 400 Bad Request or 401 Unauthorized status code with an error message.

No email or phone number provided:

If the request is missing both the email and phone-number query parameters, this response will be returned.

{
  "status": 400,
  "success": false,
  "message": "Email or phone number is required."
}

Invalid API key:

If the cv-api-key is missing or invalid, the API will return an unauthorized error.

{
  "status": 401,
  "error": "Invalid request"
}