Employees

The Employees endpoints allow you to manage employees within your organization. You can list employees, create new employees, and delete existing employees.

Base URL

https://app.trycomp.ai/v1/employees

or, if you self-host

https://app.yourdomain.com/v1/employees

Authentication

All API endpoints require authentication using an API key. You can pass the API key using one of the following methods:

In the Authorization header as a Bearer token: Authorization: Bearer {api_key}
In the X-API-Key header: X-API-Key: {api_key}

Endpoints

The following endpoints are available for managing employees:

GET /api/v1/employees - List all employees with optional filtering
GET /api/v1/employees/:id - Get a single employee by ID
POST /api/v1/employees - Create a new employee
DELETE /api/v1/employees/:id - Delete an employee by ID

List Employees

GET /api/v1/employees

Retrieves employees from your organization with optional filtering.

Query Parameters

active

boolean

Filter employees by active status. If not provided, all employees are returned.

department

string

Filter employees by department. Must be a valid department value.

string

Search employees by name or email. Performs a case-insensitive search.

Response

success

boolean

Indicates if the request was successful.

data

array

Array of employee objects, each containing:

Error Responses

success

boolean

Will be false when an error occurs.

error

string

Error message describing what went wrong.

details

object

Detailed validation errors, if applicable.

Example Request

curl -X GET "https://app.trycomp.ai/api/v1/employees?active=true&department=engineering&search=john" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clg3a4x6y000789ajdg7l8e9f",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "department": "engineering",
      "isActive": true,
      "externalEmployeeId": "EMP-123",
      "createdAt": "2023-01-15T00:00:00.000Z",
      "updatedAt": "2023-06-01T12:34:56.789Z"
    }
  ]
}

Get Employee

GET /api/v1/employees/:id

Retrieves a single employee by ID.

Path Parameters

string

required

The unique identifier of the employee to retrieve.

Response

success

boolean

Indicates if the request was successful.

data

object

The employee object.

Error Responses

success

boolean

Will be false when an error occurs.

error

string

Error message describing what went wrong.

Example Request

curl -X GET "https://app.trycomp.ai/api/v1/employees/clg3a4x6y000789ajdg7l8e9f" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "clg3a4x6y000789ajdg7l8e9f",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "department": "engineering",
    "isActive": true,
    "externalEmployeeId": "EMP-123",
    "createdAt": "2023-01-15T00:00:00.000Z",
    "updatedAt": "2023-06-01T12:34:56.789Z"
  }
}

Example Error Response

{
  "success": false,
  "error": "Employee not found"
}

Add Employee

POST /api/v1/employees

Adds a new employee to your organization.

Request Body

name

string

required

Full name of the employee.

string

required

Email address of the employee. Must be a valid email format.

department

string

Department the employee belongs to. If not provided, defaults to “none”.

isActive

boolean

Whether the employee is active. Defaults to true if not provided.

externalEmployeeId

string

Optional external identifier for the employee.

userId

string

Optional user ID to associate with the employee.

linkId

string

Optional link ID to associate with the employee.

Response

success

boolean

Indicates if the request was successful.

data

object

The newly created employee object.

Error Responses

success

boolean

Will be false when an error occurs.

error

string

Error message describing what went wrong.

details

object

Detailed validation errors, if applicable.

Example Request

curl -X POST "https://app.trycomp.ai/api/v1/employees" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "department": "marketing",
    "isActive": true,
    "externalEmployeeId": "EMP-456"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "clg3a4x6y000101ajdg7l8e9f",
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "department": "marketing",
    "isActive": true,
    "externalEmployeeId": "EMP-456",
    "createdAt": "2023-07-15T00:00:00.000Z",
    "updatedAt": "2023-07-15T00:00:00.000Z",
    "organizationId": "org_123456",
    "userId": null,
    "linkId": null
  }
}

Example Response for Validation Error

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "name": {
      "_errors": ["Name is required"]
    },
    "email": {
      "_errors": ["Valid email is required"]
    }
  }
}

Delete Employee

DELETE /api/v1/employees/:id

Deletes an employee from your organization by ID.

Path Parameters

string

required

The unique identifier of the employee to delete.

Response

success

boolean

Indicates if the request was successful.

data

object

message

string

A success message confirming the employee was deleted.

Error Responses

success

boolean

Will be false when an error occurs.

error

string

Error message describing what went wrong.

Example Request

curl -X DELETE "https://app.trycomp.ai/api/v1/employees/clg3a4x6y000789ajdg7l8e9f" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "message": "Employee deleted successfully"
  }
}

Example Error Response

{
  "success": false,
  "error": "Employee not found"
}

API Reference

​Employees

​Base URL

​Authentication

​Endpoints

​List Employees

​Query Parameters

​Response

​Error Responses

​Example Request

​Example Response

​Get Employee

​Path Parameters

​Response

​Error Responses

​Example Request

​Example Response

​Example Error Response

​Add Employee

​Request Body

​Response

​Error Responses

​Example Request

​Example Response

​Example Response for Validation Error

​Delete Employee

​Path Parameters

​Response

​Error Responses

​Example Request

​Example Response

​Example Error Response

Employees

Base URL

Authentication

Endpoints

List Employees

Query Parameters

Response

Error Responses

Example Request

Example Response

Get Employee

Path Parameters

Response

Error Responses

Example Request

Example Response

Example Error Response

Add Employee

Request Body

Response

Error Responses

Example Request

Example Response

Example Response for Validation Error

Delete Employee

Path Parameters

Response

Error Responses

Example Request

Example Response

Example Error Response