Create User

curl --request POST \
  --url https://app.hipp.health/api/v1/users \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "role": "TECHNICIAN"
}
'

{
  "message": "User created successfully",
  "user": {
    "publicId": "<string>",
    "role": "ADMIN",
    "specializations": [
      {
        "publicId": "<string>",
        "name": "<string>"
      }
    ],
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phoneNumber": "<string>",
    "npiNumber": "<string>",
    "shouldSendSMS": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "organization": {
      "name": "<string>",
      "publicId": "<string>"
    }
  }
}

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": [
        "email"
      ]
    }
  ]
}

{
  "error": "API key required",
  "statusCode": 401
}

{
  "error": "Access denied",
  "statusCode": 403
}

{
  "error": "An unexpected error occurred",
  "statusCode": 500
}

POST

users

curl --request POST \
  --url https://app.hipp.health/api/v1/users \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "role": "TECHNICIAN"
}
'

{
  "message": "User created successfully",
  "user": {
    "publicId": "<string>",
    "role": "ADMIN",
    "specializations": [
      {
        "publicId": "<string>",
        "name": "<string>"
      }
    ],
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phoneNumber": "<string>",
    "npiNumber": "<string>",
    "shouldSendSMS": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "organization": {
      "name": "<string>",
      "publicId": "<string>"
    }
  }
}

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": [
        "email"
      ]
    }
  ]
}

{
  "error": "API key required",
  "statusCode": 401
}

{
  "error": "Access denied",
  "statusCode": 403
}

{
  "error": "An unexpected error occurred",
  "statusCode": 500
}

Create a new user in your organization via API.

Headers

Authorization: Bearer <your-api-key>
Content-Type: application/json

Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "role": "TECHNICIAN",
  "phoneNumber": "+1234567890",
  "npiNumber": "1234567890",
  "shouldSendSMS": false,
  "recertificationDate": "2025-01-15T00:00:00Z",
  "providerPayors": ["abc123"],
  "specializations": ["spec_348HjqQrL-"],
  "careTeamTechnicianIds": ["usr_tech_9aBc"],
  "careTeamLeadIds": ["usr_bcba_3xYz"]
}

Field Descriptions

firstName (required): User’s first name
lastName (required): User’s last name
email (optional): User’s email address (must be unique)
role (optional): Role to assign the new user. Defaults to TECHNICIAN.
- Assignable roles: ADMIN, BILLING_MANAGER, SCHEDULING_MANAGER, CLINICIAN, TECHNICIAN, PATIENT, CAREGIVER, CLINICAL_ADMIN, PAYROLL_ADMIN
- The roles you may assign are further limited by your own role. If you request a role you are not permitted to create, the request is rejected with a 403.
phoneNumber (optional): User’s phone number
npiNumber (optional): National Provider Identifier number
shouldSendSMS (optional): Whether to send SMS notifications (defaults to false)
recertificationDate (optional): Recertification date for the user (ISO 8601 format)
providerPayors (optional): Assigns the provided payors to the User, if exists
specializations (optional): Public identifiers of specialization categories to assign to the provider. Only applied for clinical staff roles (CLINICIAN, TECHNICIAN, CLINICAL_ADMIN, CLINICAL_SUPERADMIN); ignored for other roles. Unknown or inactive categories are rejected with a 400.
careTeamTechnicianIds (optional): Public identifiers of technicians this user supervises. Only applied for clinician roles that own a care team (CLINICIAN, CLINICAL_ADMIN, CLINICAL_SUPERADMIN); ignored for other roles. Ids that are not TECHNICIAN users in your organization are silently skipped. Named to match the GET response field.
careTeamLeadIds (optional): Public identifiers of the clinicians who supervise this user. Only applied when the role is TECHNICIAN; ignored for other roles. Ids that are not care-team clinicians in your organization are silently skipped. Named to match the GET response field.

Success Response (200)

{
  "message": "User created successfully",
  "user": {
    "publicId": "usr_1234567890_abc123def",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "role": "TECHNICIAN",
    "phoneNumber": "+1234567890",
    "npiNumber": "1234567890",
    "shouldSendSMS": false,
    "createdAt": "2025-01-15T10:30:00Z",
    "specializations": [{ "publicId": "spec_348HjqQrL-", "name": "Autism" }],
    "organization": {
      "name": "Example Organization",
      "publicId": "org_abc123def456"
    }
  }
}

specializations echoes the specialization categories assigned to the created user (publicId + name). It is an empty array for non-provider roles, which never carry specializations.

The user object returned by this endpoint differs from the one returned by the Get All Users and Get User By Id endpoints, which return demographic fields such as sex, birthDate, and address information.

Error Responses

400 - Validation Error

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Expected array, received number",
      "path": ["specializations"]
    }
  ]
}

Unknown or inactive specializations are rejected with a 400 as a plain error (a single unknown id in the array rejects the whole request):

{
  "error": "One or more specialization categories were not found for this organization",
  "statusCode": 400
}

401 - Unauthorized

{
  "error": "API key required",
  "statusCode": 401
}

401 - Invalid API Key

{
  "error": "Invalid API key",
  "statusCode": 401
}

403 - Forbidden

Returned when your role does not permit creating a user with the requested role.

{
  "error": "Insufficient role hierarchy permissions to create this user role",
  "statusCode": 403
}

Examples

cURL Example

# Create a user
curl -X POST https://app.hipp.health/api/v1/users \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "role": "CLINICIAN",
    "phoneNumber": "+1234567890"
  }'

JavaScript Example

const createUser = async (userData) => {
  const response = await fetch("/api/v1/users", {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(userData),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
};

// Usage
try {
  const result = await createUser({
    firstName: "Jane",
    lastName: "Smith",
    email: "jane.smith@example.com",
    role: "CLINICIAN",
  });
  console.log("User created:", result.user);
} catch (error) {
  console.error("Error creating user:", error.message);
}

Authorizations

Authorization

string

header

required

API key authentication. Include your API key in the Authorization header as 'Bearer '

Body

application/json

firstName

string

required

User's first name

Minimum string length: 1

lastName

string

required

User's last name

Minimum string length: 1

string<email>

User's email address (must be unique)

role

enum<string>

default:TECHNICIAN

Role to assign the new user (defaults to TECHNICIAN). The roles you may assign are further restricted by your own role; requesting a role you are not permitted to create returns 403.

Available options:

ADMIN,

BILLING_MANAGER,

SCHEDULING_MANAGER,

CLINICIAN,

TECHNICIAN,

PATIENT,

CAREGIVER,

CLINICAL_ADMIN,

PAYROLL_ADMIN

phoneNumber

string

User's phone number

npiNumber

string

National Provider Identifier number

shouldSendSMS

boolean

default:false

Whether to send SMS notifications

recertificationDate

string<date-time>

Recertification date for the user

providerPayors

string[]

Assigns the provided payors to the User, if exists

specializations

string[]

Public identifiers of specialization categories to assign to the provider. Only applied for clinical staff roles (CLINICIAN, TECHNICIAN, CLINICAL_ADMIN, CLINICAL_SUPERADMIN); ignored for other roles.

careTeamTechnicianIds

string[]

Public identifiers of technicians this user supervises. Only applied for clinician roles that own a care team (CLINICIAN, CLINICAL_ADMIN, CLINICAL_SUPERADMIN); ignored for other roles. Ids that are not TECHNICIAN users in your organization are silently skipped. Named to match the GET response field.

careTeamLeadIds

string[]

Public identifiers of the clinicians who supervise this user. Only applied when the role is TECHNICIAN; ignored for other roles. Ids that are not care-team clinicians in your organization are silently skipped. Named to match the GET response field.

Response

User created successfully

message

string

Example:

"User created successfully"

user

object

The user returned immediately after creation. This shape differs from the User object returned by the list and get-by-id endpoints.

Show child attributes

API Documentation

Endpoints

Create User

Create User

Headers

Request Body

Field Descriptions

Success Response (200)

Error Responses

400 - Validation Error

401 - Unauthorized

401 - Invalid API Key

403 - Forbidden

Examples

cURL Example

JavaScript Example

Authorizations

Body

Response

​Create User

​Headers

​Request Body

​Field Descriptions

​Success Response (200)

​Error Responses

​400 - Validation Error

​401 - Unauthorized

​401 - Invalid API Key

​403 - Forbidden

​Examples

​cURL Example

​JavaScript Example

Authorizations

Body

Response

Create User

Headers

Request Body

Field Descriptions

Success Response (200)

Error Responses

400 - Validation Error

401 - Unauthorized

401 - Invalid API Key

403 - Forbidden

Examples

cURL Example

JavaScript Example