Aboard Logo
API docs by Redocly

Aboard API (1.1.0)

Download OpenAPI specification:

Aboard API Support: support@aboardhr.com License: Proprietary

Aboard documentation

Getting started

Base URL

  • Production: https://api.aboardhr.com/v1/

Authentication

The Aboard API uses Bearer token authentication. All API requests must include a valid authentication token in the Authorization header.

Getting an API token

  1. Contact your system administrator to obtain an API token
  2. Token format: The token should be a JWT (JSON Web Token) string
  3. Token scope: Tokens are scoped to specific companies and may have role-based permissions

Setting up authentication

Using cURL:

# Set your token as an environment variable
export ABOARD_API_TOKEN="your_token_here"

# Use the token in requests
curl -H "Authorization: Bearer $ABOARD_API_TOKEN" \
     https://api.aboardhr.com/v1/company

Using JavaScript/Fetch:

const token = 'your_token_here';
const response = await fetch('https://api.aboardhr.com/v1/company', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

Authentication errors

If your token is invalid or missing, you'll receive a 401 Unauthorized response with an empty body:

HTTP/1.1 401 Unauthorized
Content-Length: 0

Token security

  • Keep your token secure and never commit it to version control
  • Use environment variables to store tokens in your applications
  • Rotate tokens regularly as recommended by your security policy
  • Report compromised tokens immediately to your system administrator

Quick start examples

1. Get company information

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.aboardhr.com/v1/company

2. List employees

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.aboardhr.com/v1/employees

3. Filter employees by role

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://api.aboardhr.com/v1/employees?filter[role]=manager"

4. Get time-off requests

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.aboardhr.com/v1/time-off-requests

5. List time tracking projects

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.aboardhr.com/v1/time-tracking-projects

API features

Pagination

All list endpoints support pagination using page[limit] and page[offset] parameters:

# Get first 10 employees
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://api.aboardhr.com/v1/employees?page[limit]=10&page[offset]=0"

Filtering

Many endpoints support filtering:

  • Employees: Filter by role (employee, manager, superadmin)
  • Time-off Requests: Filter by status, time_off_policy_id, time_off_policy_type_id, date, from_date, to_date, requested_at, requested_at_from, requested_at_to
  • Time Tracking Entries: Filter by status, time_tracking_project_id, date, from_date, to_date, from_time, to_time

Response format

All responses follow the JSON:API specification with:

  • data: The main resource(s)
  • links: Pagination links
  • relationships: Links to related resources

Example response:

{
  "data": [
    {
      "id": "1",
      "type": "employees",
      "links": {
        "self": "https://api.aboardhr.com/v1/employees/1"
      },
      "attributes": {
        "first-name": "Andy",
        "last-name": "Bernard",
        "work-email": "andy-bernard@company.com",
        "role": "manager"
      },
      "relationships": {
        "time-off-requests": {
          "links": {
            "self": "https://api.aboardhr.com/v1/employees/1/relationships/time-off-requests",
            "related": "https://api.aboardhr.com/v1/employees/1/time-off-requests"
          }
        }
      }
    }
  ],
  "links": {
    "first": "https://api.aboardhr.com/v1/employees?page[limit]=20&page[offset]=0",
    "last": "https://api.aboardhr.com/v1/employees?page[limit]=20&page[offset]=0"
  }
}

Available endpoints

Company

  • GET /v1/company - Get company information

Employees

  • GET /v1/employees - List all employees
  • GET /v1/employees/{id} - Get specific employee

Bank details

  • GET /v1/bank-details - List all bank details
  • GET /v1/bank-details/{id} - Get specific bank details

Supported Bank Detail Types:

  • US: Routing number (9 digits)
  • IBAN: BIC/SWIFT code for international accounts
  • UK: Sort code (6 digits in XX-XX-XX format)
  • Canada: Institution number (3 digits) + Branch transit number (5 digits)
  • Australia: BSB code (6 digits in XXX-XXX format)
  • Denmark: Registration number (4 digits)
  • Norway: Bank code (4 digits)
  • Sweden: Clearing number (4 digits)
  • South Africa: Branch code (6 digits)
  • Singapore: Bank code (4 digits) + Branch code (3 digits)
  • New Zealand: BBAN (Basic Bank Account Number)
  • Colombia: Bank code (4 digits) + Branch code (4 digits)
  • SWIFT: International SWIFT code format

Time tracking

  • GET /v1/time-tracking-projects - List time tracking projects
  • GET /v1/time-tracking-projects/{id} - Get specific project
  • GET /v1/time-tracking-entries - List time tracking entries
  • GET /v1/time-tracking-entries/{id} - Get specific entry

Time-off management

  • GET /v1/time-off-requests - List time-off requests
  • GET /v1/time-off-requests/{id} - Get specific request
  • GET /v1/time-off-policies - List time-off policies
  • GET /v1/time-off-policies/{id} - Get specific policy
  • GET /v1/time-off-policy-types - List policy types
  • GET /v1/time-off-policy-types/{id} - Get specific policy type
  • GET /v1/holiday-calendars - List holiday calendars
  • GET /v1/holiday-calendars/{id} - Get specific holiday calendar

Organization

  • GET /v1/departments - List departments
  • GET /v1/departments/{id} - Get specific department
  • POST /v1/departments - Create a department
  • PATCH /v1/departments/{id} - Update a department
  • DELETE /v1/departments/{id} - Delete a department
  • GET /v1/job-titles - List job titles
  • GET /v1/job-titles/{id} - Get specific job title
  • POST /v1/job-titles - Create a job title
  • PATCH /v1/job-titles/{id} - Update a job title
  • DELETE /v1/job-titles/{id} - Delete a job title
  • GET /v1/locations - List locations
  • GET /v1/locations/{id} - Get specific location
  • POST /v1/locations - Create a location
  • PATCH /v1/locations/{id} - Update a location
  • DELETE /v1/locations/{id} - Delete a location

Profile attributes

  • GET /v1/profile-attributes - List custom profile attributes
  • GET /v1/profile-attributes/{id} - Get specific profile attribute
  • GET /v1/profile-attribute-options - List profile attribute options
  • GET /v1/profile-attribute-options/{id} - Get specific option
  • GET /v1/profile-attribute-values - List profile attribute values
  • GET /v1/profile-attribute-values/{id} - Get specific value

Zapier integration

Aboard connects to Zapier so profile events can trigger Zaps. Connect Aboard from within a Zap — a company superadmin authorizes the connection. See the Zapier section for the exact payloads Zapier receives.

Error handling

The API uses standard HTTP status codes:

  • 200 - Success
  • 401 - Unauthorized (invalid or missing token) - Returns empty response body
  • 404 - Resource not found
  • 422 - Validation error

Authentication errors return empty response body:

HTTP/1.1 401 Unauthorized
Content-Length: 0

Company

Company information and settings

Get company information

Retrieve information about the company associated with the authenticated user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{}

Employees

Employee records and core profile information

List employees

Retrieve a paginated list of all employees in the company

Authorizations:
bearerAuth
query Parameters
filter[role]
string
Enum: "employee" "manager" "superadmin"
Example: filter[role]=manager

Filter employees by role

filter[search]
string
Example: filter[search]=jane doe

Case-insensitive substring match against first name, last name, full name (first + space + last), and work email. Intended for resolving a specific employee (e.g. a manager) from an external system.

filter[archived]
boolean

When true, return only archived employees; when false, only active ones. Omitted, the list includes both.

filter[legal_entity_id]
string
Example: filter[legal_entity_id]=1

Only return employees whose current employment is placed in the given legal entity.

page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of employees to return per page

page[offset]
integer
Default: 0

Number of employees to skip

Responses

Response samples

Content type
application/json
{}

Create an employee

Create an employee (an Aboard Profile) in the company.

Required attributes

  • first-name, last-name
  • role — one of no_access, employee, or manager. superadmin (and its admin alias) cannot be assigned via the API; supplying it returns 400 Bad Request.

Optional attributes

  • work-email, work-phone-number
  • personal-email, personal-phone-number
  • national-identification-number
  • date-of-birth
  • daily-working-hours — defaults to 8 if omitted
  • workdays — semicolon-separated (monday;tuesday;...); defaults to Monday–Friday if omitted
  • remote-status — one of office, hybrid or remote; defaults to office if omitted
  • employment-number — only when the company manages employee IDs manually (Settings → Employee IDs → custom employee IDs). Must be unique within the company. When employee IDs are auto-generated, supplying it returns 400 Bad Request.

Inline positions & employments

Unlike other relationships, an employee's positions and employments are created inline as arrays under attributes (JSON:API relationship linkage references existing records; these create new ones). Both are optional — an employee can be created without a position — but to give the employee a job title and start date, include at least one position.

  • positions[] — each needs a role (role-id, or the deprecated job-title-id — one of them, not both, else 422) and start-date; optional level-id (a company level that must be one of the role's levels, else 422), department-id, location-id, manager-id.
  • employments[] — each requires start-date; optional probation-end-date, legal-entity-id, worker-type and employment-form-id. legal-entity-id places the employment in one of the company's legal entities; omitted, the company's default legal entity is used, and an entity from another company is rejected with 422. When worker-type / employment-form-id are supplied they seed the employment's initial terms; omitted, the employment falls back to an employee on the company's permanent form. If you supply a position but no employment, one employment is created with the first position's start-date.

Server-set / not writable

weekly-working-hours (derived) and archived-at (set by archiving the employee via DELETE). Any values supplied for these are ignored. employment-number is also server-generated unless the company uses custom employee IDs (see above).

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single employee

Retrieve detailed information about a specific employee by their ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Unique identifier for the employee

Responses

Response samples

Content type
application/json
{}

Update an employee

Update an employee's mutable attributes.

Updatable attributes

  • first-name, last-name
  • work-email, work-phone-number
  • personal-email, personal-phone-number
  • national-identification-number
  • date-of-birth
  • daily-working-hours
  • workdays — semicolon-separated (monday;tuesday;...)
  • remote-status — one of office, hybrid or remote. Any other value returns 422 Unprocessable Entity.
  • role — one of no_access, employee, or manager. superadmin (and its admin alias) cannot be assigned via the API.
  • employment-number — only when the company manages employee IDs manually (Settings → Employee IDs → custom employee IDs). Must be unique within the company; duplicates return 422 Unprocessable Entity. When employee IDs are auto-generated, this attribute is read-only and setting it returns 400 Bad Request.

Not writable

  • weekly-working-hours — derived from daily-working-hours × number of workdays.
  • archived-at — set by archiving the employee via DELETE.
  • positions, employments — can be set on create but are not editable here.

Sending a non-writable attribute, or a role the API cannot assign (e.g. superadmin), returns 400 Bad Request.

Archived employees are read-only

An employee that has been archived can no longer be modified — PATCH returns 409 Conflict with code: "profile_already_archived".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Unique identifier for the employee

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Archive an employee

Archive an employee. This is a soft delete — it follows Aboard's offboarding flow (clears the login, ends current positions, cancels upcoming approved absences) and preserves the record and its history rather than hard-deleting it.

An employee that is already archived returns 409 Conflict with code: "profile_already_archived".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Unique identifier for the employee

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Employee Details

Detailed employee data including employments, employment terms, addresses, positions, and salaries

List employments

Retrieve a paginated list of all employments

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

filter[employee_id]
string
Example: filter[employee_id]=1

Only return employments belonging to the given employee

filter[legal_entity_id]
string
Example: filter[legal_entity_id]=1

Only return employments placed in the given legal entity

Responses

Response samples

Content type
application/json
{}

Create an employment

Create an employment for an employee. An employment records the period an employee is employed, from start-date until (optionally) end-date.

Required

  • employee relationship — the employee this employment belongs to. The employee must belong to your company; referencing an id that isn't visible to your company returns 404 Not Found.
  • start-date attribute.

Optional

  • end-date attribute.
  • last-working-date attribute — requires end-date, and must fall between start-date and end-date.
  • probation-end-date attribute.
  • legal-entity relationship — the legal entity (employer of record) the employment is placed in. Omitted, the employment goes into the company's default legal entity. Referencing a legal entity from another company returns 404 Not Found.

Validation rules

  • An employee can only have one open-ended employment (without an end-date).
  • Employments for the same employee cannot overlap.

Side effects

  • Creating an employment for an archived employee restores (unarchives) them.
  • Absence cycles are opened for the time off policies the employee is assigned to.
Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Get a single employment

Retrieve employment details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment ID

Responses

Response samples

Content type
application/json
{}

Update an employment

Update an employment's dates or move it to another legal entity.

Updatable attributes

  • start-date
  • end-date — only editable on an employment that already has one. Setting an end-date on an active (open-ended) employment is rejected; terminate the employment through POST /v1/employments/{employment_id}/termination instead, which also closes any open absence cycles.
  • last-working-date — requires end-date, and must fall between start-date and end-date.
  • probation-end-date

Updatable relationships

  • legal-entity — move the employment to another of the company's legal entities. Referencing a legal entity from another company returns 404 Not Found.

Not writable

  • employee — an employment cannot be reassigned to another employee after creation.

Sending a non-writable attribute or relationship returns 400 Bad Request. Setting an end-date on an active employment returns 422 Unprocessable Entity with code: "end_date_not_editable".

Validation rules

  • An employee can only have one open-ended employment (without an end-date).
  • Employments for the same employee cannot overlap.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Delete an employment

Delete an employment. An employee always keeps at least one employment: deleting their last remaining employment returns 409 Conflict with code: "last_employment".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Terminate an employment

Terminate an employment: set its end date together with the termination details, and close the employee's open absence cycles. This is the same flow admins use in Aboard, so prefer it over a plain PATCH /v1/employments/{id} when ending an employment.

Required

  • end-date attribute.

Optional

  • last-working-date attribute — must fall between start-date and end-date.
  • termination-note attribute — free-text note, stored encrypted.
  • termination-reason relationship — resolve ids through /v1/termination-reasons. The reason must belong to your company; referencing an id that isn't visible to your company returns 404 Not Found.

An employment that already has an end date cannot be terminated again and returns 409 Conflict with code: "employment_already_terminated". Use PATCH /v1/employments/{id} to adjust the dates of an already terminated employment.

Authorizations:
bearerAuth
path Parameters
employment_id
required
string
Example: 1

Employment ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

List employment terms

Retrieve a paginated list of employment terms.

Employment terms record an employee's worker type and employment form from a given effective date. Each employment keeps a history of terms; the set with the latest effective date on or before today is the employment's current terms.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create employment terms

Create a new set of employment terms for an employment.

The terms' company and effective date are derived from the supplied employment, so a create only needs the employment and employment-form relationships plus the worker-type attribute. An optional note and effective-date can be supplied to override the derived effective date.

The employment relationship can be set on create but never moved on update.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Get a single employment terms record

Retrieve employment terms by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment terms ID

Responses

Response samples

Content type
application/json
{}

Update employment terms

Update a set of employment terms. The effective-date, worker-type and note attributes and the employment-form relationship are updatable.

The employment relationship cannot be moved — supplying a different employment is rejected.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment terms ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Delete employment terms

Delete a set of employment terms.

This mirrors the in-app terms UI: the "every employment has terms" invariant is enforced only at creation, so the last remaining terms for an employment can be deleted.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment terms ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List home addresses

Retrieve a paginated list of home addresses

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a home address

Create a new home address for an employee.

Each employee keeps a history of home addresses; the record with the latest start date on or before today is the employee's current address.

The employee relationship can be set on create but never moved on update. Referencing an employee that does not exist (or belongs to another company) returns 404.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single home address

Retrieve home address details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Home address ID

Responses

Response samples

Content type
application/json
{}

Update a home address

Update a home address. The start-date, address-line-1, address-line-2, city, zip-code and country-code attributes are updatable.

The employee relationship cannot be moved — supplying a different employee is rejected.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Home address ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a home address

Delete a home address from an employee's address history.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Home address ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List positions

Retrieve a paginated list of positions

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a position

Create a position for an employee. A position records an employee's job title, start date, employment contract and (optionally) their department, location and manager over a period of time.

Required

  • employee relationship — the employee this position belongs to.
  • One of role / job-title. role is canonical and job-title is its deprecated alias; they write the same field, so provide role (preferred) or the deprecated job-title — at least one, and not both. Sending both returns 422 with code: "conflicting_role".
  • start-date attribute.

Optional

  • employment-contract attribute — full_time (default), part_time.
  • department, location, manager relationships.
  • level (levels) — the position's level. Use a company level id that is one of the role's levels (see GET /v1/roles/{id}/levels). Required for a role whose level scheme is per-level.

Read-only

  • employment-type — derived from the employee's current employment terms (worker type + employment form), readable through the /v1/employment-terms endpoints.

Writing relationships, not IDs

The location-id, department-id and job-title-id attributes are read-only. Set the associated records through JSON:API relationships instead (employee, role, level, department, location, manager). The job-title relationship is a deprecated alias of role, still accepted for backward compatibility. Each related record must belong to your company; referencing an id that isn't visible to your company returns 404 Not Found.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Get a single position

Retrieve position details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Position ID

Responses

Response samples

Content type
application/json
{}

Update a position

Update a position's mutable attributes and relationships.

Updatable attributes

  • start-date
  • employment-contract — full_time, part_time.

Updatable relationships

  • role, level, department, location, manager — each related record must belong to your company; referencing an id that isn't visible to your company returns 404 Not Found. (job-title is a deprecated alias of role, still accepted for backward compatibility.) level is a company level (levels) that must be one of the role's levels.

Not writable

  • employment-type — read-only; derived from the employee's current employment terms (worker type + employment form), readable through the /v1/employment-terms endpoints.
  • location-id, department-id, job-title-id — read-only; set the corresponding relationship instead.
  • employee — a position cannot be reassigned to another employee after creation.

Sending a non-writable attribute returns 400 Bad Request.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Position ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

List salaries

Retrieve a paginated list of salaries

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a salary

Create a new salary for an employee.

Each employee keeps a history of salaries; the record with the latest start date on or before today is the employee's current salary. An employee can only have one salary per start date.

The employee relationship can be set on create but never moved on update. Referencing an employee that does not exist (or belongs to another company) returns 404.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single salary

Retrieve salary details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Salary ID

Responses

Response samples

Content type
application/json
{}

Update a salary

Update a salary. The currency, start-date, pay-period and amount-in-cents attributes are updatable.

The employee relationship cannot be moved — supplying a different employee is rejected.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Salary ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a salary

Delete a salary from an employee's salary history.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Salary ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Bank Details

Employee bank account and payment information

List bank details

Retrieve a paginated list of all bank details in the company

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 50
Default: 20
Example: page[limit]=20

Number of bank details to return per page

page[offset]
integer
Default: 0

Number of bank details to skip

Responses

Response samples

Content type
application/json
{}

Get bank details

Retrieve specific bank details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Bank details ID

Responses

Response samples

Content type
application/json
{}

Departments

Company departments and organizational units

List departments

Retrieve a paginated list of departments

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a department

Create a department in the company.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single department

Retrieve department details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Department ID

Responses

Response samples

Content type
application/json
{}

Update a department

Update a department's name.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Department ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a department

Delete a department. A department that is still referenced by other records (for example an upcoming hire) cannot be deleted and returns 409 Conflict with code: "record_in_use".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Department ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Job Titles

⚠️ Deprecated — use Roles instead.

Job titles are the legacy name for roles and resolve to the same records. These endpoints remain only for backward compatibility and will be removed in a future version. New integrations should use the Roles endpoints.

List job titles Deprecated

Retrieve a paginated list of job titles

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a job title Deprecated

Create a job title in the company.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single job title Deprecated

Retrieve job title details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Job title ID

Responses

Response samples

Content type
application/json
{}

Update a job title Deprecated

Update a job title's name.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Job title ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a job title Deprecated

Delete a job title. A job title that is still referenced by other records (for example an employee position or an upcoming hire) cannot be deleted and returns 409 Conflict with code: "record_in_use".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Job title ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Locations

Office locations and work sites

List locations

Retrieve a paginated list of locations

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a location

Create a location in the company.

Required attributes

  • name

Optional attributes

  • city, street-address, zip-code, country-code (ISO 3166-1 alpha-2)
  • timezone — IANA time zone identifier
  • latitude, longitude
Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single location

Retrieve location details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Location ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a location

Update a location's mutable attributes: name, city, street-address, zip-code, country-code, timezone, latitude, longitude.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Location ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a location

Delete a location. A location that is still referenced by other records (for example an upcoming hire) cannot be deleted and returns 409 Conflict with code: "record_in_use".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Location ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Employment Forms

Contractual employment forms (permanent, fixed term, ...) referenced by employment terms. Companies start with five system-default forms and can add custom ones.

List employment forms

Retrieve a paginated list of employment forms.

Employment forms describe the contractual shape of an employment (permanent, fixed term, seasonal, ...). Every company starts with five system-default forms (permanent, fixed_term, seasonal, casual_or_on_call, other) and can add custom forms on top.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create an employment form

Create a custom employment form in the company.

Both name and slug are required. The slug must be unique within the company and cannot be changed after creation; it is normalized to lowercase letters, digits and underscores.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single employment form

Retrieve employment form details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment form ID

Responses

Response samples

Content type
application/json
{}

Update an employment form

Update a custom employment form's name.

  • slug cannot be changed after creation.
  • System-default forms (permanent, fixed_term, seasonal, casual_or_on_call, other) cannot be renamed.

Both return 422 Unprocessable Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment form ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete an employment form

Delete a custom employment form. Returns 409 Conflict with code: "record_in_use" when the form cannot be deleted:

  • it is still referenced by employment terms, or
  • it is a system-default form (permanent, fixed_term, seasonal, casual_or_on_call, other).
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Employment form ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Legal Entities

The company's legal entities -- the employers of record that employments and hires are placed in. Every company has one default entity; companies with several assign each employment to one.

List legal entities

Retrieve a paginated list of the company's legal entities, in the display order configured in Aboard.

A legal entity is the employer of record for an employment -- for example a subsidiary in another country. Every company has one default legal entity, and companies with more than one assign each employment and hire to a specific entity. The list includes archived entities (archived-at set) so existing employments can still be resolved.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a legal entity

Create a legal entity in the company.

name is required and must be unique within the company. The other attributes -- organization-number, street-address, zip-code, city, country-code -- are optional.

is-default and archived-at are read-only; sending either returns 400 Bad Request. Manage the default entity and archiving from Settings → Legal entities in Aboard.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single legal entity

Retrieve legal entity details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Legal entity ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a legal entity

Update a legal entity's mutable attributes: name, organization-number, street-address, zip-code, city, country-code.

is-default and archived-at are read-only; sending either returns 400 Bad Request. Manage the default entity and archiving from Settings → Legal entities in Aboard.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Legal entity ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a legal entity

Delete a legal entity. Returns 409 Conflict with code: "record_in_use" when the entity cannot be deleted:

  • it is the company's default legal entity, or
  • it is still referenced by employments.

Unhandled hires do not block deletion; their legal-entity is cleared. To retire an entity that still has employments, archive it from Settings → Legal entities in Aboard instead.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Legal entity ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Termination Reasons

Read-only list of the company's termination reasons (resignation or termination). Integrations resolve a reason ID here before terminating an employment.

List termination reasons

Retrieve a paginated list of the company's termination reasons.

Integrations resolve a termination reason ID here before terminating an employment through POST /v1/employments/{employment_id}/termination.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Get a single termination reason

Retrieve termination reason details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Termination reason ID

Responses

Response samples

Content type
application/json
{}

Roles

Roles within the organization (the job-architecture successor to job titles).

List roles

Retrieve a paginated list of roles.

Roles are the job-architecture successor to job titles (same underlying records). Prefer this over the deprecated GET /v1/job-titles.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a role

Create a role in the company.

Besides name, a role can carry an optional code and description, and a family relationship. The family must reference one of the company's families (see GET /v1/families); an unknown family returns 404.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a single role

Retrieve role details by ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Role ID

Responses

Response samples

Content type
application/json
{}

Update a role

Update a role's name, code, description, or family relationship.

The family must reference one of the company's families (see GET /v1/families); an unknown family returns 404.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Role ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a role

Delete a role. A role that is still referenced by other records (for example an employee position or an upcoming hire) cannot be deleted and returns 409 Conflict with code: "record_in_use".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Role ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List a role's levels

Retrieve the company levels connected to a role, in ladder order. Each entry is addressed by the level id and carries a code and a name (the per-role override, or the level's own name when not overridden). Use a returned level id for a hire's or position's level relationship.

Authorizations:
bearerAuth
path Parameters
role_id
required
string
Example: 1

Role ID

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ]
}

Add a level to a role

Connect a company level to a role. The id must be one of the company's levels (see GET /v1/levels). Provide an optional per-role name override; when omitted, the level's own name is used.

Errors

  • 422 with code: "invalid_level" (no source pointer) when data.id is not one of the company's levels.
  • 422 with code: "validation_error" and source.pointer: "/data/attributes/level-id" when the level is already connected to the role.
Authorizations:
bearerAuth
path Parameters
role_id
required
string
Example: 1

Role ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update a role level

Update the per-role name override for a level connected to a role.

Authorizations:
bearerAuth
path Parameters
role_id
required
string
Example: 1

Role ID

level_id
required
string
Example: 8

Level ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Remove a level from a role

Disconnect a level from a role. A level that is still in use by a position cannot be removed and returns 409 Conflict with code: "record_in_use".

Authorizations:
bearerAuth
path Parameters
role_id
required
string
Example: 1

Role ID

level_id
required
string
Example: 8

Level ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Levels

Company levels — the seniority ladder. Connect levels to roles via /v1/roles/{id}/levels.

List levels

Retrieve a paginated list of the company's levels, in ladder order.

Levels are the company's seniority ladder. Connect them to roles via /v1/roles/{id}/levels.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a level

Create a level in the company. code is unique per company; a duplicate returns 422.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a level

Retrieve a level by ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Level ID

Responses

Response samples

Content type
application/json
{
  • "data": {}
}

Update a level

Update a level's code, name or description. code is unique per company; a duplicate returns 422.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Level ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a level

Delete a level. A level that is still in use by positions cannot be deleted and returns 409 Conflict with code: "record_in_use".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Level ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Families

Job families — groupings of related roles.

List families

Retrieve a paginated list of the company's job families.

Families are groupings of related roles. Assign a role to a family via the family relationship on /v1/roles.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Create a family

Create a job family in the company. name is unique per company; a duplicate returns 422.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a family

Retrieve a family by ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Family ID

Responses

Response samples

Content type
application/json
{}

Update a family

Update a family's name. name is unique per company; a duplicate returns 422.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Family ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a family

Delete a family.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Family ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Hires

Pre-activation employee records (e.g. from an ATS) that admins later turn into Aboard profiles. The first write endpoints in the public API.

List hires

Retrieve a paginated list of hires (pre-activation employees) for the company.

Hires are records created by integrations (e.g. an ATS) or by managers in advance of activating an Aboard Profile. Once a hire has been handled in Aboard, its handled attribute becomes true and the record becomes read-only via the API.

Authorizations:
bearerAuth
query Parameters
filter[external-source]
string
Example: filter[external-source]=teamtailor

Filter by the name of the external system that created the hire (e.g. teamtailor). Typically combined with filter[external-id] to look up a specific record without storing Aboard IDs locally.

filter[external-id]
string
Example: filter[external-id]=tt-7421

Filter by the hire's ID in the external system.

filter[handled]
boolean

Filter by whether the hire has been handled in Aboard.

  • false — returns only hires the integration can still modify.
  • true — returns only hires that have been turned into Aboard profiles.

Omitted: returns both.

page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of hires to return per page

page[offset]
integer
Default: 0

Number of hires to skip

Responses

Response samples

Content type
application/vnd.api+json
{}

Create a hire

Create a hire in the company.

Required

Attributes — first-name, last-name, personal-email.

Relationships — department, location, and one of role / job-title. role is canonical and job-title is its deprecated alias; they write the same field, so provide role (preferred) or the deprecated job-title — at least one, and not both. Sending both returns 422 with code: "conflicting_role".

An unknown relationship id, or one belonging to another company (role, department, location, manager, etc.), returns 404 Not Found.

Optional attributes

  • personal-phone-number
  • birthday
  • gender — one of male, female, non_binary, other, prefer_not_to_say
  • address-line-1, address-line-2, city, zip-code, country-code
  • planned-start-date
  • worker-type — classification of the worker; drives the employment terms created on activation. Defaults to employee.
  • employment-type — deprecated, use worker-type and the employment-form relationship instead. Kept for backward compatibility; a legacy value is mapped onto worker-type / employment-form unless those are set explicitly.
  • employment-contract
  • probation-months — probation length in whole months, 1 to 6. Omit or send null for no probation. The last day is worked out from planned-start-date and returned as probation-end-date.
  • probation-end-date — deprecated, send probation-months instead. Still accepted and converted to the nearest whole month from planned-start-date, capped at 6. If both are sent, probation-months wins.
  • salary-amount-in-cents, salary-currency, salary-pay-period
  • notes
  • external-source, external-id — pair them to make the hire findable via filter[external-source] / filter[external-id] on the list endpoint. The combination is unique per company. Immutable once set (no PATCH).
  • created-by-name, created-by-email — name and email of the person who created the hire in the source system, when the creator is not an Aboard user. Immutable once set (no PATCH).
  • referred-by-email — work email of the employee who referred the hire. Aboard resolves it to an active employee and sets referred-by. An address that matches no employee is kept, with referred-by left empty; a malformed one returns 422.

Optional relationships

  • level (levels) — the hire's level. Use a company level id that is one of the role's levels (see GET /v1/roles/{id}/levels). A hire can be created without one, but a per-level role can't be activated into an employee until a level is set.
  • manager (employees)
  • referred-by (employees) — the employee who referred the hire. Takes precedence over referred-by-email in the same request.
  • onboarding-template (onboarding-templates)
  • employment-form (employment-forms) — the form used for the employment terms created on activation.
  • legal-entity (legal-entities) — the legal entity the employment created on activation is placed in. Omitted, the company's default legal entity is used. Referencing a legal entity from another company returns 404 Not Found.
  • time-off-policies (time-off-policies, many)

Server-set / not writable

created-by, profile, handled, created-at, updated-at. Any values supplied for these are ignored.

Authorizations:
bearerAuth
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Get a single hire

Retrieve hire details by ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Hire ID

Responses

Response samples

Content type
application/vnd.api+json
{}

Update a hire

Update a hire's mutable attributes and relationships.

Updatable attributes

  • first-name, last-name
  • personal-email, personal-phone-number
  • birthday, gender
  • address-line-1, address-line-2, city, zip-code, country-code
  • planned-start-date
  • employment-type, employment-contract
  • probation-months — probation length in whole months, 1 to 6, or null for none
  • probation-end-date — deprecated, converted to probation-months (see the Hire schema)
  • salary-amount-in-cents, salary-currency, salary-pay-period
  • notes
  • referred-by-email — resolved to an active employee by work email; null clears it

Updatable relationships

  • manager
  • referred-by — the employee who referred the hire; wins over referred-by-email in the same request
  • role, department, location (job-title is a deprecated alias of role)
  • level — the hire's level; a company level (levels) that must be one of the role's levels
  • onboarding-template
  • employment-form
  • legal-entity — the legal entity the employment created on activation is placed in. Referencing a legal entity from another company returns 404 Not Found.
  • time-off-policies

Not writable

  • external-source, external-id — settable on create, then frozen as the integration's lookup key.
  • created-by-name, created-by-email — settable on create, then frozen.
  • created-by, profile, handled, created-at, updated-at — server-managed.

Values supplied for any of these are ignored.

Handled hires are read-only

A hire that has already been handled in Aboard (handled: true) cannot be modified — PATCH returns 409 Conflict with code: "hire_already_handled". The same applies to the relationship endpoints, e.g. PATCH or DELETE on /v1/hires/{id}/relationships/referred-by.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Hire ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Delete a hire

Delete a hire that has not yet been handled in Aboard.

A hire that has already been handled (handled: true) cannot be deleted via the API — DELETE returns 409 Conflict with code: "hire_already_handled".

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Hire ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Upload or replace a hire's avatar

Upload an avatar image for a hire by sending the bytes as multipart/form-data.

Re-uploading silently replaces any existing avatar. The response is the full Hire resource, including the populated avatar attribute with small, medium, and original URLs.

Multipart upload

Binary uploads are the documented exception to the JSON:API-only write convention used elsewhere in this API. The request body is multipart/form-data with a single part:

  • file — the binary image file. Accepted content types match the supported image formats (image/jpeg, image/png, image/webp, image/gif, image/svg+xml).

No JSON data part is required — the avatar has no other writable attributes.

Handled hires are read-only

A hire that has already been handled in Aboard (handled: true) cannot have its avatar modified — PUT returns 409 Conflict with code: "hire_already_handled". After activation, manage the avatar on the resulting employee profile instead.

Example

PUT /v1/hires/42/avatar
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data; boundary=----X

------X
Content-Disposition: form-data; name="file"; filename="avatar.jpg"
Content-Type: image/jpeg

<binary>
------X--
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 42

ID of the hire

Request Body schema: multipart/form-data
required
file
required
string <binary>

The image file to attach.

Responses

Response samples

Content type
application/vnd.api+json
{}

Remove a hire's avatar

Detach the hire's current avatar and clear the cached URLs. Returns the updated Hire resource with avatar: null.

Returns 409 Conflict when the hire has already been handled in Aboard.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 42

ID of the hire

Responses

Response samples

Content type
application/vnd.api+json
{}

Hire Documents

Files (contracts, IDs, signed offers, etc.) attached to a hire before activation. On activation, each HireDocument is copied to the resulting employee profile as a ProfileDocument.

List documents for a hire

Retrieve a paginated list of documents attached to a hire.

Documents are arbitrary files (contracts, IDs, signed offers, etc.) attached to a Hire by integrations before the hire is activated. When the hire is later activated in Aboard, each HireDocument becomes a ProfileDocument on the resulting employee profile.

Authorizations:
bearerAuth
path Parameters
hire_id
required
string
Example: 42

ID of the parent hire

query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of documents to return per page

page[offset]
integer
Default: 0

Number of documents to skip

Responses

Response samples

Content type
application/vnd.api+json
{}

Attach a document to a hire

Create a new document attached to a hire by uploading a file together with its metadata.

Multipart upload

Binary uploads are the documented exception to the JSON:API-only write convention used elsewhere in this API. The request body is multipart/form-data with two parts:

  • data — a string containing the JSON:API document (attributes + relationships). Must declare type: "hire-documents" and include the profile-document-category relationship.
  • file — the binary file part. Maximum size: 30 MB.

If validation fails, the response is 422 and no record is created.

Resolving profile-document-category

Integrations resolve the category ID up front via GET /v1/profile-document-categories. The category carries over verbatim to the resulting ProfileDocument when the hire is activated.

Handled hires are read-only

A hire that has already been handled in Aboard (handled: true) cannot have new documents attached — POST returns 409 Conflict with code: "hire_already_handled".

Example

POST /v1/hires/42/hire-documents
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data; boundary=----X

------X
Content-Disposition: form-data; name="data"
Content-Type: application/json

{
  "data": {
    "type": "hire-documents",
    "attributes": { "name": "Signed offer" },
    "relationships": {
      "profile-document-category": {
        "data": { "type": "profile-document-categories", "id": "7" }
      }
    }
  }
}
------X
Content-Disposition: form-data; name="file"; filename="offer.pdf"
Content-Type: application/pdf

<binary>
------X--
Authorizations:
bearerAuth
path Parameters
hire_id
required
string
Example: 42

ID of the parent hire

Request Body schema: multipart/form-data
required
data
required
string

JSON:API document, as a string. Must have type: "hire-documents" and include the profile-document-category relationship. Optional attribute: name.

file
required
string <binary>

The file to attach. Maximum size 30 MB.

Responses

Response samples

Content type
application/vnd.api+json
{}

Get a single hire document

Retrieve a single document attached to a hire, including a signed URL to download the file.

Authorizations:
bearerAuth
path Parameters
hire_id
required
string
Example: 42

ID of the parent hire

id
required
string
Example: 1

Hire document ID

Responses

Response samples

Content type
application/vnd.api+json
{}

Update a hire document

Update a hire document's metadata.

Updatable

  • name (attribute)
  • profile-document-category (relationship)

Not writable

  • file-* attributes — replace the file by deleting the document and creating a new one.
  • hire relationship — determined by the URL.
  • created-at, updated-at — server-managed.

Handled hires are read-only

A hire that has already been handled in Aboard (handled: true) cannot have its documents modified — PATCH returns 409 Conflict with code: "hire_already_handled".

Authorizations:
bearerAuth
path Parameters
hire_id
required
string
Example: 42

ID of the parent hire

id
required
string
Example: 1

Hire document ID

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{}

Delete a hire document

Delete a document attached to a hire.

A document attached to a hire that has already been handled (handled: true) cannot be deleted via the API — DELETE returns 409 Conflict with code: "hire_already_handled".

Authorizations:
bearerAuth
path Parameters
hire_id
required
string
Example: 42

ID of the parent hire

id
required
string
Example: 1

Hire document ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Profile Document Categories

Read-only list of document categories used by both ProfileDocuments and HireDocuments. Integrations resolve a category ID here before posting a hire document.

List profile document categories

Retrieve a paginated list of profile document categories for the company.

Profile document categories are the buckets used to classify ProfileDocuments (and HireDocuments before activation). Integrations resolve a category ID through this endpoint before posting a HireDocument.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of categories to return per page

page[offset]
integer
Default: 0

Number of categories to skip

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "links": {}
}

Get a single profile document category

Retrieve a profile document category by ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 7

Profile document category ID

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Documents

Read-only list of company documents, such as policies employees are asked to read or sign.

List documents

Retrieve a paginated list of company documents, sorted by name. Deleted documents are not included.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of documents to return per page

page[offset]
integer
Default: 0

Number of documents to skip

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "links": {}
}

Get a single document

Retrieve a company document by ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Document ID

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Document Acknowledgements

Read-only record of which employees have read or signed each company document. Useful for syncing policy acceptance to compliance tools.

List document acknowledgements

Retrieve a paginated list of completed document acknowledgements. E-signature requests that have not been signed yet, and acknowledgements of deleted documents, are not included.

Use include=employee,document to fetch the related employee and document in the same request.

Authorizations:
bearerAuth
query Parameters
filter[document_id]
string
Example: filter[document_id]=1

Filter acknowledgements by document ID

filter[employee_id]
string
Example: filter[employee_id]=1

Filter acknowledgements by employee ID

include
string
Example: include=employee,document

Comma-separated related resources to include

page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of acknowledgements to return per page

page[offset]
integer
Default: 0

Number of acknowledgements to skip

Responses

Response samples

Content type
application/vnd.api+json
{}

Get a single document acknowledgement

Retrieve a document acknowledgement by ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Document acknowledgement ID

Responses

Response samples

Content type
application/vnd.api+json
{}

Onboarding Templates

Reusable onboarding templates used to bootstrap new-hire experiences

List onboarding templates

Retrieve a paginated list of onboarding templates for the company. Useful for resolving an onboarding template ID when creating hires through the API.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Get a single onboarding template

Retrieve onboarding template details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Onboarding template ID

Responses

Response samples

Content type
application/json
{}

Profile Attributes

Custom profile attributes, options, and values for employees

List profile attributes

Retrieve a paginated list of custom profile attributes defined for the company

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Get a single profile attribute

Retrieve profile attribute details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Profile attribute ID

Responses

Response samples

Content type
application/json
{}

List profile attribute options

Retrieve a paginated list of options for profile attributes

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Get a single profile attribute option

Retrieve profile attribute option details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Profile attribute option ID

Responses

Response samples

Content type
application/json
{}

List profile attribute values

Retrieve a paginated list of profile attribute values assigned to employees

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Get a single profile attribute value

Retrieve profile attribute value details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Profile attribute value ID

Responses

Response samples

Content type
application/json
{}

Time Tracking

Time tracking projects and entries

List time tracking entries

Retrieve a paginated list of time tracking entries with optional filtering

Authorizations:
bearerAuth
query Parameters
filter[status]
string
Enum: "active" "archived"
Example: filter[status]=active

Filter entries by status

filter[time_tracking_project_id]
string
Example: filter[time_tracking_project_id]=1

Filter entries by project ID

filter[date]
string <date>
Example: filter[date]=2025-01-15

Filter entries by exact date (YYYY-MM-DD format)

filter[from_date]
string <date>
Example: filter[from_date]=2025-01-01

Filter entries starting on or after this date (YYYY-MM-DD format)

filter[to_date]
string <date>
Example: filter[to_date]=2025-01-31

Filter entries ending on or before this date (YYYY-MM-DD format)

filter[from_time]
string <date-time>
Example: filter[from_time]=2025-01-15T09:00:00Z

Filter entries starting on or after this timestamp (ISO 8601 format)

filter[to_time]
string <date-time>
Example: filter[to_time]=2025-01-15T18:00:00Z

Filter entries ending on or before this timestamp (ISO 8601 format)

page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of entries to return per page

page[offset]
integer
Default: 0

Number of entries to skip

Responses

Response samples

Get a single time tracking entry

Retrieve time tracking entry details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Time tracking entry ID

Responses

Response samples

Content type
application/json
{}

List time tracking projects

Retrieve a paginated list of all time tracking projects

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of projects to return per page

page[offset]
integer
Default: 0

Number of projects to skip

Responses

Response samples

Content type
application/json
{}

Get a single time tracking project

Retrieve detailed information about a specific time tracking project by its ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Unique identifier for the time tracking project

Responses

Response samples

Content type
application/json
{}

Time Off

Time-off requests, policies, and policy types

List time-off requests

Retrieve a paginated list of time-off requests with optional filtering

Authorizations:
bearerAuth
query Parameters
filter[status]
string
Enum: "pending" "approved" "declined" "cancelled"
Example: filter[status]=approved

Filter requests by status

filter[time_off_policy_id]
string
Example: filter[time_off_policy_id]=1

Filter requests by policy ID

filter[time_off_policy_type_id]
string
Example: filter[time_off_policy_type_id]=1

Filter requests by policy type ID

filter[date]
string <date>
Example: filter[date]=2025-07-15

Filter requests that contain a specific date (YYYY-MM-DD format). Returns requests where the date falls between start_date and end_date.

filter[from_date]
string <date>
Example: filter[from_date]=2025-07-01

Filter requests starting on or after this date (YYYY-MM-DD format)

filter[to_date]
string <date>
Example: filter[to_date]=2025-07-31

Filter requests ending on or before this date (YYYY-MM-DD format)

filter[requested_at]
string <date>
Example: filter[requested_at]=2025-06-01

Filter requests created on a specific date (YYYY-MM-DD format)

filter[requested_at_from]
string <date>
Example: filter[requested_at_from]=2025-06-01

Filter requests created on or after this date (YYYY-MM-DD format)

filter[requested_at_to]
string <date>
Example: filter[requested_at_to]=2025-06-30

Filter requests created on or before this date (YYYY-MM-DD format)

page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of requests to return per page

page[offset]
integer
Default: 0

Number of requests to skip

Responses

Response samples

Content type
application/json
{}

Get a single time-off request

Retrieve detailed information about a specific time-off request by its ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Unique identifier for the time-off request

Responses

Response samples

Content type
application/json
{}

List time-off policy types

Retrieve a paginated list of time-off policy types

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of policy types to return per page

page[offset]
integer
Default: 0

Number of policy types to skip

Responses

Response samples

Content type
application/json
{}

Get a single time-off policy type

Retrieve detailed information about a specific time-off policy type by its ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Unique identifier for the time-off policy type

Responses

Response samples

Content type
application/json
{}

List time-off policies

Retrieve a paginated list of time-off policies

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of policies to return per page

page[offset]
integer
Default: 0

Number of policies to skip

Responses

Response samples

Content type
application/json
{}

Get a single time-off policy

Retrieve detailed information about a specific time-off policy by its ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Unique identifier for the time-off policy

Responses

Response samples

Content type
application/json
{}

Holiday Calendars

Read-only list of public holiday calendars. Integrations resolve a calendar ID here before assigning one to a hire.

List holiday calendars

Retrieve a paginated list of public holiday calendars for the company. Useful for resolving a holiday calendar ID when creating hires through the API.

Authorizations:
bearerAuth
query Parameters
page[limit]
integer <= 100
Default: 20
Example: page[limit]=20

Number of records per page

page[offset]
integer
Default: 0

Number of records to skip

Responses

Response samples

Content type
application/json
{}

Get a single holiday calendar

Retrieve holiday calendar details by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1

Holiday calendar ID

Responses

Response samples

Content type
application/json
{}

Zapier

Aboard's Zapier integration lets profile events trigger Zaps. Connect Aboard from within a Zap — a company superadmin authorizes the connection — and pick one of two triggers. Everything else is handled by the Zapier platform; there is nothing to call or configure on the Aboard API.

Trigger Fires when
New Profile An employee profile is created
Updated Profile A profile or its home address is created or updated

Each event is delivered to the Zap as a JSON payload. Delivery is at-least-once; Zapier deduplicates by the payload's top-level id. The exact payload shapes are documented below so you know precisely what data reaches Zapier.

Sensitive data never leaves Aboard: payloads exclude national IDs, bank details, dates of birth, and emergency contacts, and changes to those fields never fire a trigger.

New Profile (webhook payload) Webhook

POSTed to a subscribed Zap's catch URL when an employee profile is created. Delivery is at-least-once — Zapier deduplicates by the top-level id. Failed deliveries are retried on server errors, rate limits, and timeouts.

Authorizations:
bearerAuth
Request Body schema: application/json
id
string <uuid>

Delivery idempotency key — stable across retries of the same delivery, distinct per event and destination. Zapier deduplicates incoming hook payloads by this field; it is not meant to be mapped into Zap steps.

type
string
Value: "new_profile"

Identifies the trigger that fired.

occurredAt
string <date-time>

When the profile was created (ISO 8601, always carries a zone).

object

Snapshot of the new employee profile — the non-sensitive fields of the new-employee form.

Responses

Request samples

Content type
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "type": "new_profile",
  • "occurredAt": "2026-01-01T00:00:00Z",
  • "profile": {
    }
}

Updated Profile (webhook payload) Webhook

POSTed to a subscribed Zap's catch URL when an employee profile is updated or its home address is created/updated. Delivery is at-least-once — Zapier deduplicates by the top-level id. Failed deliveries are retried on server errors, rate limits, and timeouts.

Authorizations:
bearerAuth
Request Body schema: application/json
id
string <uuid>

Delivery idempotency key — stable across retries of the same delivery, distinct per event and destination. Zapier deduplicates incoming hook payloads by this field; it is not meant to be mapped into Zap steps.

type
string
Value: "updated_profile"

Identifies the trigger that fired.

occurredAt
string <date-time>

When the change happened (ISO 8601, always carries a zone).

object

Snapshot of the employee profile's non-sensitive contact fields. Phone numbers and ZIP codes are strings. Sensitive fields (national ID, bank details, date of birth, emergency contacts) are never included, and changes to them never fire this trigger.

Responses

Request samples

Content type
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "type": "updated_profile",
  • "occurredAt": "2026-01-01T00:00:00Z",
  • "profile": {
    }
}