Skip to main content
POST
/
v1
/
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>",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phoneNumber": "<string>",
    "npiNumber": "<string>",
    "shouldSendSMS": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "organization": {
      "name": "<string>",
      "publicId": "<string>"
    }
  }
}

​
Create User

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"]
}

​
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

​
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",
    "organization": {
      "name": "Example Organization",
      "publicId": "org_abc123def456"
    }
  }
}
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

{
  "error": "Validation error",
  "details": [
    {
      "code": "invalid_string",
      "message": "Valid email is required",
      "path": ["email"]
    }
  ]
}

​
401 - Unauthorized

{
  "error": "API key required"
}

​
401 - Invalid API Key

{
  "error": "Invalid API key"
}

​
403 - Forbidden

Returned when your role does not permit creating a user with the requested role. 
{
  "error": "Access denied"
}

​
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
​
email
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

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.