# Create new employee

Creates a new employee record in the system. This endpoint does NOT automatically send an invitation. To send an invitation, use the send invitation endpoint after creating the employee. Only employees with the EMPLOYEE role can be created through this endpoint.

Endpoint: POST /companies/{companyId}/users
Version: 0.0.1
Security: partnerAdminAuth

## Header parameters:

  - `X-Aslan-Timestamp` (integer, required)
    Unix epoch timestamp of the request in seconds.
    Example: 1730000000

## Path parameters:

  - `companyId` (string, required)
    The unique identifier for the company

## Request fields (application/json):

  - `firstName` (string, required)
    Employee's legal first name
    Example: "Sarah"

  - `lastName` (string, required)
    Employee's legal last name
    Example: "Johnson"

  - `email` (string, required)
    Primary work email address for the employee
    Example: "sarah.johnson@techflow.com"

  - `additionalEmail` (string)
    Secondary or personal email address for account recovery and notifications
    Example: "sarah.j.personal@gmail.com"

  - `phoneNumber` (string)
    Contact phone number in international E.164 format
    Example: "+447123456789"

  - `externalPayrollId` (string)
    Employee identifier from the external payroll system for reconciliation purposes
    Example: "PAY-2024-00847"

  - `annualGrossSalary` (number)
    Employee's annual gross salary in GBP (must be greater than 0)
    Example: 45000

  - `startDate` (string)
    Employee's employment start date with the company
    Example: "2024-01-15"

  - `payCalendarId` (string)
    Reference to the pay calendar schedule this employee follows
    Example: "c5d6e7f8-9a0b-4c5d-8e9f-0a1b2c3d4e5f"

  - `salaried` (boolean, required)
    Indicates whether the employee is on a salaried payment structure
    Example: true

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique system identifier for the employee
    Example: "f7e6d5c4-b3a2-4918-8e7d-6c5b4a3f2e1d"

  - `status` (string, required)
    Current status of the employee with Aslan:
* CREATED - Employee record created but invitation not yet sent
* INVITED - Invitation to join Aslan has been sent to the employee
* ACTIVE - Employee is actively enrolled and can access earned wage access benefits
* DELETED - Employee record has been removed from the system
* PAUSED - Employee's access to benefits is temporarily suspended
* LEFT - Employee has left the company and is no longer eligible
    Enum: "CREATED", "INVITED", "ACTIVE", "DELETED", "PAUSED", "LEFT"

  - `firstName` (string, required)
    Employee's legal first name
    Example: "Sarah"

  - `lastName` (string, required)
    Employee's legal last name
    Example: "Johnson"

  - `email` (string, required)
    Primary work email address for the employee
    Example: "sarah.johnson@techflow.com"

  - `additionalEmail` (string)
    Secondary or personal email address for account recovery and notifications
    Example: "sarah.j.personal@gmail.com"

  - `role` (string, required)
    Employee's role within the company and their permission level in Aslan:
* EMPLOYEE - Standard employee with access to personal wage access features
* MANAGER - Manager with additional reporting and team oversight capabilities
* ADMIN - Company administrator with full company management capabilities
* SUPER_ADMIN - Super administrator with extended system-level permissions
    Enum: "EMPLOYEE", "MANAGER", "ADMIN", "SUPER_ADMIN"

  - `companyId` (string, required)
    Unique identifier of the company this employee belongs to
    Example: "a3f2e1d0-5c4b-4a3e-9f8e-7d6c5b4a3e2f"

  - `phoneNumber` (string)
    Contact phone number in international format
    Example: "+44 7123 456789"

  - `externalPayrollId` (string)
    Employee identifier from the external payroll system for reconciliation purposes
    Example: "PAY-2024-00847"

  - `annualGrossSalary` (number)
    Employee's annual gross salary in GBP, used for eligibility calculations
    Example: 45000

  - `globalAllowancePercentage` (integer)
    Global allowance percentage for wage access eligibility
    Example: 50

  - `odpAllowancePercentage` (integer)
    On-demand pay allowance percentage for wage access eligibility
    Example: 25

  - `salaryHistory` (array)
    Historical record of salary changes for the employee

  - `salaryHistory.annualGrossSalary` (number, required)
    Annual gross salary amount in GBP for this period
    Example: 42000

  - `salaryHistory.appliesDate` (string, required)
    Date when this salary amount applies from
    Example: "2024-01-01"

  - `invitedAt` (string)
    Date and time when the employee was invited to join Aslan
    Example: "2024-04-09T09:00:00+00:00"

  - `joinDate` (string)
    Date and time when the employee completed registration and joined Aslan
    Example: "2024-04-10T11:45:00+00:00"

  - `startDate` (string)
    Employee's employment start date with the company
    Example: "2024-01-15"

  - `terminationDate` (string)
    Employee's employment termination date, if applicable
    Example: "2025-03-31"

  - `payCalendarId` (string)
    Reference to the pay calendar schedule this employee follows
    Example: "c5d6e7f8-9a0b-4c5d-8e9f-0a1b2c3d4e5f"

  - `friendlyId` (string, required)
    Human-readable alphanumeric identifier for the employee (max 10 characters)
    Example: "F7E6D5C4B3"

  - `onUnpaidLeave` (boolean, required)
    Indicates whether the employee is currently on unpaid leave

  - `emailVerified` (boolean, required)
    Indicates whether the employee's email address has been verified
    Example: true

  - `phoneNumberVerified` (boolean, required)
    Indicates whether the employee's phone number has been verified
    Example: true

  - `suspicious` (boolean)
    Flag indicating if the account has been marked for suspicious activity review

  - `salaried` (boolean, required)
    Indicates whether the employee is on a salaried payment structure
    Example: true

  - `createdAt` (string, required)
    Timestamp when the employee was initially registered in the system
    Example: "2024-04-08T10:30:00Z"

  - `createdBy` (string, required)
    System identifier of the user or service that created this employee record
    Example: "b2c3d4e5-6f7a-4b5c-8d9e-0f1a2b3c4d5e"

  - `updatedAt` (string)
    Timestamp of the most recent update to the employee record
    Example: "2024-10-05T11:30:45Z"

  - `updatedBy` (string)
    System identifier of the user or service that last updated this employee record
    Example: "c3d4e5f6-7a8b-5c6d-9e0f-1a2b3c4d5e6f"

  - `deletedAt` (string)
    Timestamp when the employee was soft-deleted from the system
    Example: "2024-12-01T16:20:00Z"

  - `deletedBy` (string)
    System identifier of the user or service that deleted this employee record
    Example: "d4e5f6a7-8b9c-6d7e-0f1a-2b3c4d5e6f7a"

## Response 400 fields (application/json):

  - `timestamp` (string, required)
    Timestamp when the error occurred
    Example: "2024-10-10T15:45:30Z"

  - `status` (integer, required)
    HTTP status code
    Example: 400

  - `error` (string, required)
    HTTP status text
    Example: "Bad Request"

  - `message` (string, required)
    Human-readable error message describing what went wrong
    Example: "Invalid date range: fromDate must be before toDate"

  - `path` (string, required)
    API endpoint path where the error occurred
    Example: "/api/v1/companies/a3f2e1d0-5c4b-4a3e-9f8e-7d6c5b4a3e2f/users/f7e6d5c4-b3a2-4918-8e7d-6c5b4a3f2e1d/spend-report"

  - `errors` (array)
    Detailed validation errors (present for validation failures)

  - `errors.field` (string, required)
    Name of the field that failed validation
    Example: "email"

  - `errors.message` (string, required)
    Validation error message for this field
    Example: "Email address is already in use"

  - `errors.rejectedValue` (string)
    The value that was rejected (may be omitted for sensitive data)
    Example: "sarah.johnson@techflow.com"

  - `traceId` (string)
    Unique identifier for tracing this error in logs
    Example: "a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"

## Response 401 fields (application/json):

  - `timestamp` (string, required)
    Timestamp when the error occurred
    Example: "2024-10-10T15:45:30Z"

  - `status` (integer, required)
    HTTP status code
    Example: 400

  - `error` (string, required)
    HTTP status text
    Example: "Bad Request"

  - `message` (string, required)
    Human-readable error message describing what went wrong
    Example: "Invalid date range: fromDate must be before toDate"

  - `path` (string, required)
    API endpoint path where the error occurred
    Example: "/api/v1/companies/a3f2e1d0-5c4b-4a3e-9f8e-7d6c5b4a3e2f/users/f7e6d5c4-b3a2-4918-8e7d-6c5b4a3f2e1d/spend-report"

  - `errors` (array)
    Detailed validation errors (present for validation failures)

  - `errors.field` (string, required)
    Name of the field that failed validation
    Example: "email"

  - `errors.message` (string, required)
    Validation error message for this field
    Example: "Email address is already in use"

  - `errors.rejectedValue` (string)
    The value that was rejected (may be omitted for sensitive data)
    Example: "sarah.johnson@techflow.com"

  - `traceId` (string)
    Unique identifier for tracing this error in logs
    Example: "a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"

## Response 403 fields (application/json):

  - `timestamp` (string, required)
    Timestamp when the error occurred
    Example: "2024-10-10T15:45:30Z"

  - `status` (integer, required)
    HTTP status code
    Example: 400

  - `error` (string, required)
    HTTP status text
    Example: "Bad Request"

  - `message` (string, required)
    Human-readable error message describing what went wrong
    Example: "Invalid date range: fromDate must be before toDate"

  - `path` (string, required)
    API endpoint path where the error occurred
    Example: "/api/v1/companies/a3f2e1d0-5c4b-4a3e-9f8e-7d6c5b4a3e2f/users/f7e6d5c4-b3a2-4918-8e7d-6c5b4a3f2e1d/spend-report"

  - `errors` (array)
    Detailed validation errors (present for validation failures)

  - `errors.field` (string, required)
    Name of the field that failed validation
    Example: "email"

  - `errors.message` (string, required)
    Validation error message for this field
    Example: "Email address is already in use"

  - `errors.rejectedValue` (string)
    The value that was rejected (may be omitted for sensitive data)
    Example: "sarah.johnson@techflow.com"

  - `traceId` (string)
    Unique identifier for tracing this error in logs
    Example: "a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"

## Response 404 fields (application/json):

  - `timestamp` (string, required)
    Timestamp when the error occurred
    Example: "2024-10-10T15:45:30Z"

  - `status` (integer, required)
    HTTP status code
    Example: 400

  - `error` (string, required)
    HTTP status text
    Example: "Bad Request"

  - `message` (string, required)
    Human-readable error message describing what went wrong
    Example: "Invalid date range: fromDate must be before toDate"

  - `path` (string, required)
    API endpoint path where the error occurred
    Example: "/api/v1/companies/a3f2e1d0-5c4b-4a3e-9f8e-7d6c5b4a3e2f/users/f7e6d5c4-b3a2-4918-8e7d-6c5b4a3f2e1d/spend-report"

  - `errors` (array)
    Detailed validation errors (present for validation failures)

  - `errors.field` (string, required)
    Name of the field that failed validation
    Example: "email"

  - `errors.message` (string, required)
    Validation error message for this field
    Example: "Email address is already in use"

  - `errors.rejectedValue` (string)
    The value that was rejected (may be omitted for sensitive data)
    Example: "sarah.johnson@techflow.com"

  - `traceId` (string)
    Unique identifier for tracing this error in logs
    Example: "a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"

## Response 409 fields (application/json):

  - `timestamp` (string, required)
    Timestamp when the error occurred
    Example: "2024-10-10T15:45:30Z"

  - `status` (integer, required)
    HTTP status code
    Example: 400

  - `error` (string, required)
    HTTP status text
    Example: "Bad Request"

  - `message` (string, required)
    Human-readable error message describing what went wrong
    Example: "Invalid date range: fromDate must be before toDate"

  - `path` (string, required)
    API endpoint path where the error occurred
    Example: "/api/v1/companies/a3f2e1d0-5c4b-4a3e-9f8e-7d6c5b4a3e2f/users/f7e6d5c4-b3a2-4918-8e7d-6c5b4a3f2e1d/spend-report"

  - `errors` (array)
    Detailed validation errors (present for validation failures)

  - `errors.field` (string, required)
    Name of the field that failed validation
    Example: "email"

  - `errors.message` (string, required)
    Validation error message for this field
    Example: "Email address is already in use"

  - `errors.rejectedValue` (string)
    The value that was rejected (may be omitted for sensitive data)
    Example: "sarah.johnson@techflow.com"

  - `traceId` (string)
    Unique identifier for tracing this error in logs
    Example: "a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"

## Response 500 fields (application/json):

  - `timestamp` (string, required)
    Timestamp when the error occurred
    Example: "2024-10-10T15:45:30Z"

  - `status` (integer, required)
    HTTP status code
    Example: 400

  - `error` (string, required)
    HTTP status text
    Example: "Bad Request"

  - `message` (string, required)
    Human-readable error message describing what went wrong
    Example: "Invalid date range: fromDate must be before toDate"

  - `path` (string, required)
    API endpoint path where the error occurred
    Example: "/api/v1/companies/a3f2e1d0-5c4b-4a3e-9f8e-7d6c5b4a3e2f/users/f7e6d5c4-b3a2-4918-8e7d-6c5b4a3f2e1d/spend-report"

  - `errors` (array)
    Detailed validation errors (present for validation failures)

  - `errors.field` (string, required)
    Name of the field that failed validation
    Example: "email"

  - `errors.message` (string, required)
    Validation error message for this field
    Example: "Email address is already in use"

  - `errors.rejectedValue` (string)
    The value that was rejected (may be omitted for sensitive data)
    Example: "sarah.johnson@techflow.com"

  - `traceId` (string)
    Unique identifier for tracing this error in logs
    Example: "a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"