Employees API

This guide covers the API endpoints for managing employees in the Revenue Recognition System. Employees represent individual workers within your organization who may be assigned to projects, tasks, or involved in various business processes.

All employee data is isolated by organization context, ensuring that each organization can only access and modify its own employee records.

Schema

Field	Type	Description	Required
id	UUID	Unique identifier (system-generated)	Read-only
organizationId	String	Organization this employee belongs to	Read-only
name	String	Full name of the employee	Yes
displayName	String	Display name for the employee	No
code	String	Employee code or identifier	No
entityTypes	Array	Entity types (always includes 'Employee')	Yes
email	String	Email address of the employee	No
phone	String	Phone number of the employee	No
website	String	Personal website URL	No
address	Object	Employee address details (see below)	No
parentEntityId	UUID	Parent entity identifier	No
primaryContactId	UUID	Primary contact identifier	No
taxId	String	Tax identification number	No
description	String	Description of the employee	No
notes	String	Additional notes about the employee	No
customFields	Object	Custom fields for additional data	No
metadata	Object	Employee-specific metadata (see below)	No
status	String	Status: 'active', 'inactive', or 'archived'	Yes
isActive	Boolean	Whether the employee is active (default: true)	Yes
createdAt	DateTime	When the record was created	Read-only
updatedAt	DateTime	When the record was last updated	Read-only

Address Object

Field	Type	Description	Required
id	UUID	Unique identifier for the address	No
addressee	String	Addressee name	No
companyName	String	Company name	No
attention	String	Attention line	No
phoneNumber	String	Phone number associated with address	No
line1	String	First line of street address	No
line2	String	Second line of street address	No
city	String	City	No
stateProvince	String	State or province	No
postalCode	String	Postal or ZIP code	No
countryCode	String	ISO 3166-1 alpha-2 country code	No

Employee Metadata Object

Field	Type	Description	Required
employeeId	String	Internal employee ID or badge number	No
department	String	Department the employee belongs to	No
title	String	Job title of the employee	No
reportsTo	UUID	ID of the employee's manager	No
startDate	Date	Employment start date	No
endDate	Date	Employment end date (if applicable)	No
employmentType	String	Type: 'full-time', 'part-time', 'contractor', 'intern'	No

Authentication

All employee API endpoints require authentication with a valid JWT token. The token should be included in the Authorization header as a Bearer token. Organization context is automatically determined from the authenticated session.

Endpoints

Create Employee

Create a new employee within your organization.

Name
Endpoint
Type
POST /employees
Description
Name
Content-Type
Type
application/json
Description

Request Body

Name
name
Type
string
Required
Description
Full name of the employee
Name
displayName
Type
string
Description
Display name for the employee
Name
code
Type
string
Description
Employee code or identifier
Name
entityTypes
Type
array
Required
Description
Entity types (must include 'Employee')
Name
email
Type
string
Description
Email address of the employee
Name
phone
Type
string
Description
Phone number of the employee
Name
website
Type
string
Description
Personal website URL
Name
address
Type
object
Description
Employee address details
Name
parentEntityId
Type
string (UUID)
Description
Parent entity identifier
Name
primaryContactId
Type
string (UUID)
Description
Primary contact identifier
Name
taxId
Type
string
Description
Tax identification number
Name
description
Type
string
Description
Description of the employee
Name
notes
Type
string
Description
Additional notes
Name
customFields
Type
object
Description
Custom fields for additional data
Name
metadata
Type
object
Description
Employee-specific metadata including department, title, etc.
Name
status
Type
string
Description
Employee status: 'active', 'inactive', or 'archived'
Name
isActive
Type
boolean
Description
Whether the employee is active

Request

curl -X POST https://api.example.com/employees \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "name": "John Doe",
    "displayName": "John",
    "code": "EMP001",
    "entityTypes": ["Employee"],
    "email": "john.doe@company.com",
    "phone": "555-123-4567",
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "stateProvince": "CA",
      "postalCode": "94105",
      "countryCode": "US"
    },
    "metadata": {
      "employeeId": "EMP001",
      "department": "Engineering",
      "title": "Senior Developer",
      "employmentType": "full-time",
      "startDate": "2024-01-15"
    },
    "status": "active",
    "isActive": true
  }'

Response

{
  "id": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
  "organizationId": "org_123456789",
  "name": "John Doe",
  "displayName": "John",
  "code": "EMP001",
  "entityTypes": ["Employee"],
  "email": "john.doe@company.com",
  "phone": "555-123-4567",
  "website": null,
  "address": {
    "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
    "addressee": null,
    "companyName": null,
    "attention": null,
    "phoneNumber": null,
    "line1": "123 Main St",
    "line2": null,
    "city": "San Francisco",
    "stateProvince": "CA",
    "postalCode": "94105",
    "countryCode": "US"
  },
  "parentEntityId": null,
  "primaryContactId": null,
  "taxId": null,
  "description": null,
  "notes": null,
  "customFields": null,
  "metadata": {
    "employeeId": "EMP001",
    "department": "Engineering",
    "title": "Senior Developer",
    "reportsTo": null,
    "startDate": "2024-01-15",
    "endDate": null,
    "employmentType": "full-time"
  },
  "status": "active",
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T12:33:59.048Z"
}

List Employees

Retrieve a paginated list of employees in your organization.

Name
Endpoint
Type
GET /employees
Description

Query Parameters

Name
page
Type
number
Description
Page number for pagination
Name
limit
Type
number
Description
Number of items per page (max: 100)
Name
orderBy
Type
string
Description
Field to sort by (name, createdAt, updatedAt)
Name
orderDirection
Type
string
Description
Sort direction (asc, desc)
Name
status
Type
string
Description
Filter by status (active, inactive, archived)
Name
search
Type
string
Description
Search term to filter results
Name
isActive
Type
boolean
Description
Filter by active status

Request

curl -X GET "https://api.example.com/employees?page=1&limit=10&status=active" \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
      "organizationId": "org_123456789",
      "name": "John Doe",
      "displayName": "John",
      "code": "EMP001",
      "entityTypes": ["Employee"],
      "email": "john.doe@company.com",
      "phone": "555-123-4567",
      "website": null,
      "address": {
        "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
        "line1": "123 Main St",
        "city": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "countryCode": "US"
      },
      "metadata": {
        "employeeId": "EMP001",
        "department": "Engineering",
        "title": "Senior Developer",
        "employmentType": "full-time"
      },
      "status": "active",
      "isActive": true,
      "createdAt": "2025-05-11T12:33:59.048Z",
      "updatedAt": "2025-05-11T12:33:59.048Z"
    }
  ],
  "total": 25,
  "page": 1,
  "limit": 10,
  "totalPages": 3
}

Get Employee

Retrieve a specific employee by ID.

Name
Endpoint
Type
GET /employees/{id}
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the employee to retrieve

Request

curl -X GET https://api.example.com/employees/f47f0ea2-77bd-4578-8c76-0116d473cc27 \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "id": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
  "organizationId": "org_123456789",
  "name": "John Doe",
  "displayName": "John",
  "code": "EMP001",
  "entityTypes": ["Employee"],
  "email": "john.doe@company.com",
  "phone": "555-123-4567",
  "website": null,
  "address": {
    "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
    "line1": "123 Main St",
    "city": "San Francisco",
    "stateProvince": "CA",
    "postalCode": "94105",
    "countryCode": "US"
  },
  "metadata": {
    "employeeId": "EMP001",
    "department": "Engineering",
    "title": "Senior Developer",
    "employmentType": "full-time",
    "startDate": "2024-01-15"
  },
  "status": "active",
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T12:33:59.048Z"
}

Update Employee

Update an existing employee.

Name
Endpoint
Type
PUT /employees/{id}
Description
Name
Content-Type
Type
application/json
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the employee to update

Request Body

All fields from the create endpoint can be updated except read-only fields.

Request

curl -X PUT https://api.example.com/employees/f47f0ea2-77bd-4578-8c76-0116d473cc27 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "displayName": "Johnny",
    "metadata": {
      "department": "Engineering",
      "title": "Lead Developer",
      "employmentType": "full-time"
    },
    "status": "active"
  }'

Response

{
  "id": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
  "organizationId": "org_123456789",
  "name": "John Doe",
  "displayName": "Johnny",
  "code": "EMP001",
  "entityTypes": ["Employee"],
  "email": "john.doe@company.com",
  "phone": "555-123-4567",
  "metadata": {
    "employeeId": "EMP001",
    "department": "Engineering",
    "title": "Lead Developer",
    "employmentType": "full-time",
    "startDate": "2024-01-15"
  },
  "status": "active",
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T14:45:22.183Z"
}

Delete Employee

Delete an employee.

Name
Endpoint
Type
DELETE /employees/{id}
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the employee to delete

Request

curl -X DELETE https://api.example.com/employees/f47f0ea2-77bd-4578-8c76-0116d473cc27 \
  -H "Authorization: Bearer your_jwt_token"

Response

204 No Content

Find Employees by Department

Retrieve all employees in a specific department.

Name
Endpoint
Type
GET /employees/department/{department}
Description

Path Parameters

Name
department
Type
string
Required
Description
Department name

Request

curl -X GET https://api.example.com/employees/department/Engineering \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
      "name": "John Doe",
      "displayName": "John",
      "metadata": {
        "department": "Engineering",
        "title": "Senior Developer"
      },
      "status": "active"
    }
  ]
}

Find Direct Reports

Retrieve all employees who report to a specific manager.

Name
Endpoint
Type
GET /employees/reports-to/{managerId}
Description

Path Parameters

Name
managerId
Type
string (UUID)
Required
Description
Manager's employee ID

Request

curl -X GET https://api.example.com/employees/reports-to/a23c7de4-9821-4f56-9ab3-0c245b88e129 \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
      "name": "John Doe",
      "displayName": "John",
      "metadata": {
        "department": "Engineering",
        "title": "Senior Developer",
        "reportsTo": "a23c7de4-9821-4f56-9ab3-0c245b88e129"
      },
      "status": "active"
    }
  ]
}

Find Employee by Internal ID

Retrieve an employee by their internal employee ID or badge number.

Name
Endpoint
Type
GET /employees/by-employee-id/{employeeId}
Description

Path Parameters

Name
employeeId
Type
string
Required
Description
Employee's internal ID or badge number

Request

curl -X GET https://api.example.com/employees/by-employee-id/EMP001 \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "id": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
  "name": "John Doe",
  "displayName": "John",
  "code": "EMP001",
  "metadata": {
    "employeeId": "EMP001",
    "department": "Engineering",
    "title": "Senior Developer"
  },
  "status": "active"
}

Error Responses

The API returns standard HTTP status codes and error messages in a consistent format.

{
  "error": "Error description",
  "details": [
    {
      "message": "Specific error detail",
      "path": ["field", "path"]
    }
  ]
}

Common errors include:

Status Code	Error	Description
400	Bad Request	Invalid input data or validation error
401	Unauthorized	Missing or invalid authentication token
404	Not Found	Employee with the specified ID not found
500	Internal Server Error	Server error occurred

Best Practices

Employee Status Management

The status field allows you to track the employment lifecycle:

active: Currently employed and active
inactive: Temporarily inactive (e.g., on leave)
archived: No longer employed

Instead of deleting employees, consider changing their status to archived to maintain historical data for reporting and audit purposes.

Employee Metadata

Use the metadata object to store employee-specific information such as:

Department assignment
Job title and role
Reporting relationships
Employment dates and type

This structured approach allows for better querying and reporting on employee data.

Custom Fields

The customFields object allows you to store additional organization-specific data that doesn't fit into the standard schema. This provides flexibility while maintaining the core structure.

Code Example

Here's an example of how to use the employees API with JavaScript:

// Create a new employee
async function createEmployee(employeeData) {
  const response = await fetch('https://api.example.com/employees', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getAuthToken()}`
    },
    body: JSON.stringify({
      name: employeeData.name,
      entityTypes: ['Employee'],
      email: employeeData.email,
      metadata: {
        department: employeeData.department,
        title: employeeData.title,
        employmentType: 'full-time'
      },
      status: 'active',
      isActive: true
    })
  });

  if (!response.ok) {
    throw new Error('Failed to create employee');
  }

  return await response.json();
}

// Find employees in a department
async function getEmployeesByDepartment(department) {
  const response = await fetch(
    `https://api.example.com/employees/department/${encodeURIComponent(department)}`,
    {
      headers: {
        'Authorization': `Bearer ${getAuthToken()}`
      }
    }
  );

  if (!response.ok) {
    throw new Error('Failed to fetch employees');
  }

  return await response.json();
}