Introduction

AlexisHR API is currently in preview. This means that small, backward incompatible changes might be introduced while in preview. The changes will be documented and communicated. Subscribe to updates

Authentication

curl https://api.alexishr.com/v1/employee \
  -H "Authorization: Bearer <your_access_token>"

Authenticate your account when using the API by including your secret Access Token in the request. Manage your Access Tokens.

Authentication is performed by passing the Access Token in the Authorization header.

Structure

You will find the structure of the API to be highly uniform and consistent. Typically every resource can be accessed via a top level endpoint, such as /v1/employee. For every such resource, you can perform some of the following operations:

Operations

Roles

The Access Tokens will have owner permission on the account

Filters

Some of the list endpoints allow to filter results by certain conditions. Refer to specific resources to find out what criteria are allowed. Below is a list of the different conditions.

$eq

Find all results matching the attribute value specified.

GET /v1/example?filters[fieldName][$eq]=value

Can also be simplified like this.

GET /v1/example?filters[fieldName]=value

$neq

Find all results not matching the attribute value specified.

GET /v1/example?filters[fieldName][$neq]=value

$gt, $gte

Find all results where the value is more ($gt) or more and equal ($gte) to a given value.

GET /v1/example?filters[startDate][$gte]=2020-01-01

$lt, $lte

Find all results where the value is less ($lt) or less and equal ($lte) to a given value.

GET /v1/example?filters[startDate][$lte]=2020-01-01

$in, $nin

Find all results matching ($in) or not matching ($nin) any of the attribute values specified.

GET /v1/example?filters[fieldName][$in][]=value1&filters[fieldName][$in][]=value2

$between

Find all results between two values specified.

GET /v1/example?filters[startDate][$between][]=2020-01-01&filters[startDate][$between][]=2020-12-31

Versioning

Each version of the API is guaranteed to be compatible with the resources of the same version. When we make breaking changes to the API a new version will be published

Changelog

2023-12-20

Field [updated] added for filter & select for Get Many Employments and Get Many Employees.

2021-03-15

First draft was published

Web Hooks

AlexisHR provides webhook functionality to notify your application about employee-related events in real-time. This allows you to stay synchronized with employee data changes without constantly polling the API.

Standard Payload

This is the generic/standard payload structure which will be included in each of the webhook events:

{
  "eventType": "employee.created",
  "timestamp": "2024-08-16T12:34:56Z",
  "version": "1.0",
  "metadata": {
    "sourceSystem": "alexis"
  },
  "data": { 
    "eventSpecificDataField01": "someValue01",
    "eventSpecificDataField02": "someValue02" 
  }
}

Employee Events

Employee Created

Event Type: employee.created

Description: Triggered when an employee is created.

Example Payload:

{
  "eventType": "employee.created",
  "timestamp": "2024-08-16T12:34:56Z",
  "version": "1.0",
  "data": {
    "employeeId": "usr_123456789",
    "userId": "643eb2de2d0d6b001933c779",
    "employeeNumber": "123",
    "workEmail": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2024-08-16T12:34:56Z",
    "updatedAt": "2024-08-16T12:34:56Z"
  },
  "metadata": {
    "sourceSystem": "alexis"
  }
}

Employee Updated

Event Type: employee.updated

Description: Triggered when updating employee fields or when adding and updating employee custom fields.

Note: The changes field for update events will not be included in Version 1.0. This feature will be discussed further and implemented if deemed feasible.

Example Payload:

{
  "eventType": "employee.updated",
  "timestamp": "2024-08-16T13:45:67Z",
  "version": "1.0",
  "data": {
    "employeeId": "usr_123456789",
    "userId": "643eb2de2d0d6b001933c779",
    "employeeNumber": "123",
    "workEmail": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2024-08-16T12:34:56Z",
    "updatedAt": "2024-08-16T13:45:67Z"
  },
  "metadata": {
    "sourceSystem": "alexis"
  },
  "changes": {
      "updatedFields": ["name", "workEmail"],
      "name": {
          "from": "John Doe",
          "to": "John Smith"
      },
      "workEmail": {
          "from": "user@example.com",
          "to": "newemail@example.com"
      }
  }
}

Employee Deleted

Event Type: employee.deleted

Description: Triggered when deleting the employee's profile.

Example Payload:

{
  "eventType": "employee.deleted",
  "timestamp": "2024-09-03T15:00:00Z",
  "version": "1.0",
  "data": {
    "employeeId": "usr_123456789",
    "userId": "643eb2de2d0d6b001933c779",
    "employeeNumber": "123",
    "workEmail": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2024-08-16T12:34:56Z",
    "deletedAt": "2024-09-03T15:00:00Z"
  },
  "metadata": {
    "sourceSystem": "alexis"
  }
}

Employee Offboarded

Event Type: employee.offboarded

Description: Triggered when an employee is offboarded and the effective date of the offboarding is reached.

Example Payload:

{
  "eventType": "employee.offboarded",
  "timestamp": "2024-09-03T15:30:00Z",
  "version": "1.0",
  "data": {
    "employeeId": "usr_123456789",
    "userId": "643eb2de2d0d6b001933c779",
    "employeeNumber": "123",
    "workEmail": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2024-08-16T12:34:56Z",
    "offboardedAt": "2024-09-03T15:30:00Z",
    "terminationDate": "2024-09-03",
    "terminationReason": "Voluntary Resignation"
  },
  "metadata": {
    "sourceSystem": "alexis"
  }
}

Employee Onboarded

Event Type: employee.onboarded

Description: Triggered when an employee is onboarded and have been invited into the system.

Example Payload:

{
  "eventType": "employee.onboarded",
  "timestamp": "2024-09-03T16:00:00Z",
  "version": "1.0",
  "data": {
    "employeeId": "usr_123456789",
    "userId": "643eb2de2d0d6b001933c779",
    "employeeNumber": "123",
    "workEmail": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2024-08-16T12:34:56Z",
    "hireDate": "2024-09-03",
    "title": "Software Engineer",
    "departmentId": "123456798"
  },
  "metadata": {
    "sourceSystem": "alexis"
  }
}