Create User | Gradii API Documentation

curl -X POST https://gradii.ai/api/v2/users/create \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "SecurePass123!",
  "role": "hr",
  "jobTitle": "HR Manager",
  "department": "Human Resources",
  "phoneNumber": "+1234567890",
  "timezone": "America/New_York",
  "emailNotifications": true,
  "smsNotifications": false,
  "language": "en",
  "isActive": true,
  "otpLoginEnabled": true,
  "socialLoginEnabled": true,
  "autoVerifyEmail": true
}'

{
  "success": true,
  "data": {
    "user": {
      "id": "user-uuid",
      "companyId": "company-uuid",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "role": "hr",
      "jobTitle": "HR Manager",
      "department": "Human Resources",
      "phoneNumber": "+1234567890",
      "isActive": true,
      "emailVerified": "2024-01-28T10:00:00.000Z",
      "otpLoginEnabled": true,
      "socialLoginEnabled": true,
      "createdAt": "2024-01-28T10:00:00.000Z",
      "updatedAt": "2024-01-28T10:00:00.000Z"
    },
    "company": {
      "id": "company-uuid",
      "name": "Acme Corp",
      "email": "admin@acme.com"
    }
  },
  "message": "User created successfully",
  "timestamp": "2024-01-28T10:00:00Z",
  "version": "2.0"
}

Create a new user for your company. Only email is required - other fields auto-generated if not provided.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

Email domain must match company domain if configured Password auto-generated if not provided (12 chars with lowercase, uppercase, numbers, symbols) Names default to ‘Unknown User’ if not provided User is pre-verified if autoVerifyEmail=true

emailstringRequiredformat: "email"

User email (lowercase, max 255 chars)

firstNamestringOptional

First name (1-100 chars, letters/spaces/hyphens only, default: ‘Unknown’)

lastNamestringOptional

Last name (1-100 chars, letters/spaces/hyphens only, default: ‘User’)

passwordstringOptional

Password (8-128 chars, must contain lowercase, uppercase, number, auto-generated if not provided)

rolestringOptional

owner|hr|interviewer|recruiter (default: hr)

jobTitlestringOptional

Job title (max 100 chars)

departmentstringOptional

Department (max 100 chars)

phoneNumberstringOptional

Phone number (max 20 chars, format: +[0-9 ()-])

timezonestringOptional

Timezone (max 50 chars)

preferenceslist of anyOptional

User preferences array (default: [])

emailNotificationsbooleanOptional

Enable email notifications (default: true)

smsNotificationsbooleanOptional

Enable SMS notifications (default: false)

languagestringOptional

Preferred language (max 10 chars)

isActivebooleanOptional

User active status (default: true)

otpLoginEnabledbooleanOptional

Enable OTP login (default: true)

socialLoginEnabledbooleanOptional

Enable social login (default: true)

externalIdstringOptional

External HRMS system ID (max 255 chars)

externalSourcestringOptional

Name of external HRMS system (max 100 chars)

metadatamap from strings to anyOptional

Additional metadata from HRMS

autoVerifyEmailbooleanOptional

Auto-verify email for trusted systems (default: true)

Response

User created successfully

successbooleanOptional

dataobjectOptional

messagestringOptional

timestampstringOptional

versionstringOptional

Errors

400

Bad Request Error

409

Conflict Error