Create user

POST/api/v1/users

Creates a new user in the organization associated with the API key. The user is always created with the USER role.

cv-api-key

Productionhttps://api.care360-next.carevalidate.com/api/v1/users

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/users

Headers

Headers

cv-api-keystringrequired

Your unique API key for authentication.

Content-Typestringrequired

Must be application/json.

Example: application/json

Request Body

Body Parameters

actionstringrequired

The action to be performed. Must be CREATE_USER.

Values:CREATE_USER

dataobjectrequired

An object containing the new user's details.

Show 17 child properties

emailstringrequired

The user's email address. Must be unique across the platform.

Example: john.doe@example.com

firstNamestringoptional

The user's first name.

Example: John

lastNamestringoptional

The user's last name.

Example: Doe

dobstringoptional

The user's date of birth in YYYY-MM-DD format.

Example: 1995-10-01

genderstringoptional

The user's gender.

Values:MALEFEMALEOTHER

phoneNumberstringoptional

The user's phone number. Must be in E.164 format.

Example: +11234567890

addressstringoptional

The user's street address. Should not be a PO Box.

Example: 123 ABC street

address2stringoptional

Optional second line for the address (e.g., apartment or suite number).

Example: Apt 2

citystringoptional

The user's city.

Example: NYC

statestringoptional

The user's state in 2-character abbreviation format.

Example: NY

countrystringoptional

The user's country code in 2-character abbreviation format.

Example: US

postalCodestringoptional

The user's postal code (e.g., 12345 or 12345-6789).

Example: 01010

allergiesstringoptional

The user's allergies.

Example: Peanuts, Shellfish

currentMedicationsstringoptional

The user's current medications.

Example: Aspirin, Metformin

healthConditionsstringoptional

The user's health conditions.

Example: Diabetes, Hypertension

languagePreferencesarrayoptional

The user's language preferences. No duplicate values allowed.

Example: ["ENGLISH", "SPANISH"]

communicationobjectoptional

An object containing the user's notification preferences.

Show 2 child properties

smsNotificationsDisabledbooleanoptional

Set to true to disable SMS notifications for this user.

Example: true

emailNotificationsDisabledbooleanoptional

Set to true to disable email notifications for this user.

Example Request

cURL

curl --location '<BASE_URL>/api/v1/users' \
--header 'cv-api-key: <redacted>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "action": "CREATE_USER",
  "data": {
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "dob": "1995-10-01",
      "phoneNumber": "+11234567890",
      "gender": "MALE",
      "address": "123 ABC street",
      "address2": "Apt 2",
      "city": "NYC",
      "state": "NY",
      "country": "US",
      "postalCode": "01010",
      "allergies": "Peanuts, Shellfish",
      "currentMedications": "Aspirin, Metformin",
      "healthConditions": "Diabetes, Hypertension",
      "languagePreferences": ["ENGLISH", "SPANISH"],
      "communication": {
          "smsNotificationsDisabled": true,
          "emailNotificationsDisabled": false
      }
  }
}'

JavaScript

const response = await fetch('<BASE_URL>/api/v1/users', {
method: 'POST',
headers: {
  'cv-api-key': '<redacted>',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  action: 'CREATE_USER',
  data: {
    email: 'john.doe@example.com',
    firstName: 'John',
    lastName: 'Doe',
    dob: '1995-10-01',
    phoneNumber: '+11234567890',
    gender: 'MALE',
    address: '123 ABC street',
    address2: 'Apt 2',
    city: 'NYC',
    state: 'NY',
    country: 'US',
    postalCode: '01010',
    allergies: 'Peanuts, Shellfish',
    currentMedications: 'Aspirin, Metformin',
    healthConditions: 'Diabetes, Hypertension',
    languagePreferences: ['ENGLISH', 'SPANISH'],
    communication: {
      smsNotificationsDisabled: true,
      emailNotificationsDisabled: false,
    },
  },
}),
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
  '<BASE_URL>/api/v1/users',
  headers={
      'cv-api-key': '<redacted>',
      'Content-Type': 'application/json',
  },
  json={
      'action': 'CREATE_USER',
      'data': {
          'email': 'john.doe@example.com',
          'firstName': 'John',
          'lastName': 'Doe',
          'dob': '1995-10-01',
          'phoneNumber': '+11111111111',
          'gender': 'MALE',
          'address': '123 ABC street',
          'address2': 'Apt 2',
          'city': 'NYC',
          'state': 'NY',
          'country': 'US',
          'postalCode': '01010',
          'allergies': 'Peanuts, Shellfish',
          'currentMedications': 'Aspirin, Metformin',
          'healthConditions': 'Diabetes, Hypertension',
          'languagePreferences': ['ENGLISH', 'SPANISH'],
          'communication': {
              'smsNotificationsDisabled': True,
              'emailNotificationsDisabled': False,
          },
      },
  },
)
print(response.json())

Responses

▶200User created successfullyThe user was created successfully. Returns the new user object including the generated id.

{
  "status": 200,
  "success": true,
  "message": "User created successfully",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "dob": "1995-10-01T00:00:00.000Z",
      "phoneNumber": "+11234567890",
      "gender": "MALE",
      "address": "123 ABC street",
      "address2": "Apt 2",
      "city": "NYC",
      "state": "NY",
      "country": "US",
      "postalCode": "01010",
      "allergies": "Peanuts, Shellfish",
      "currentMedications": "Aspirin, Metformin",
      "healthConditions": "Diabetes, Hypertension",
      "languagePreferences": [
        "ENGLISH",
        "SPANISH"
      ],
      "communication": {
        "smsNotificationsDisabled": true,
        "emailNotificationsDisabled": false
      }
    }
  }
}

▶400Email already existsA user with the provided email already exists in the platform.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "User with email {email} already exists"
}

▶400Missing required fieldThe only required field is email. This error is returned when email is not provided.

{
  "status": 400,
  "success": false,
  "message": "Validation error",
  "error": "data.email: Invalid email"
}

▶400Invalid field valueA field failed validation — e.g., invalid email format, dob not a real calendar date, invalid state code, phone not in E.164 format, unknown gender value.

{
  "status": 400,
  "success": false,
  "message": "Validation error",
  "error": "data.phoneNumber: Invalid phone number"
}

▶400Unrecognized fieldAn unknown key was passed in the data or communication object.

{
  "status": 400,
  "success": false,
  "message": "Validation error",
  "error": "data, Unrecognized key: \"unknownField\""
}

▶400Invalid API keyThe provided API key is invalid or does not correspond to any organization.

{
  "status": 400,
  "success": false,
  "message": "Organization not found"
}

Try It Out

Try itAPI Playground

▶