Introduction

The HeavenHR public REST API for accessing and storing employee and company data

Last Updated: 2020-11-30
Customers can access a number of publicly exposed HeavenHR endpoints to facilitate data sharing and synchronization needs.

Contact information:
publicapi@heavenhr.de

Access Control

# example nodeJS code to generate api key from client id and client secret

var CryptoJS = require("crypto-js");

var client_id = ("heavenHr_clientId");
var client_secret = ("heavenHr_clientSecret");
var rawStr = client_id + ":" + client_secret;
var utf8Str = CryptoJS.enc.Utf8.parse(rawStr);
var heavenHrApiKey = CryptoJS.enc.Base64.stringify(utf8Str);

console.log('encrypted:', heavenHrApiKey);

# Before your application can access private data using a HeavenHR API, 
# it must obtain an access token that grants access to that API.
curl "https://api.heavenhr.com/api/v2/oauth2/token?grant_type=client_credentials&scope=all"
  -X GET -H "Authorization: Basic heaven_hr_api_key"

1. Obtain OAuth 2.0 credentials for the company. Contact the customer care for getting your client id and client secret

2. Generate the api key using client id and client secret. Obtain an access token using api key.

3. Access token need to be passed to all the subsequent API calls.

4. Refresh the access token, if necessary

HeavenHR expects for the authorization key to be included in all API requests to the server in a header that looks like the following:

Information

Health Check

To verify the status of the API, verify the following returns a 200 response.

curl 'https://api.heavenhr.com/api/v2/health/check' 

> Returns the following for a healthy response:

{
  "message": "OK"
}

Employees

Create a new employee

curl 'https://api.heavenhr.com/api/v2/employees/ -X POST ' 

> The above command returns JSON structured like this:

{
    "startDate": "2017-04-13",
    "endOfContract": "2022-04-13",
    "professionalEmail": "professionalEmail@heavenhr.de",
    "jobTitle": "Head of Sales",
    "permanentOrTemporary": "PERMANENT",
    "streetPersonal": "Griefwalderstrasse",
    "streetNumberPersonal": 219,
    "additionalContractInformation": "The employee has the right to take leave 24 days a year.",
    "locationId": "_bE1Zi2WRANH76y0vDbdEdA_",
    "employeeNumber": 716,
    "gender": "MALE",
    "nationality": "DE",
    "occupation": "Manager",
    "firstName": "Max",
    "fullTimeOrPartTime": "FULL_TIME",
    "employmentType": "FREELANCER",
    "lastName": "Musterman",
    "jobStatus": "CREATED_EXISTING",
    "mobileWork": 63121,
    "dateOfBirth": "1984-07-17",
    "departmentId": "_EaH3L12VPSVhuSDPqkKIdg_",
    "phonePersonal": 4921348182,
    "costCenterId": "_3q4nkYvIocIJDUhyZJh5dQ_",
    "email": "email@heavenhr.de",
    "sendOnboardingEmail": true,
    "customAttributes": [
       {
        "id": "_Aeqew@adq3dsfADRaqw",
        "name": "Customer attribute Name",
        "value": "I am superman"
       }
    ],
    "contract": {
        "grossSalary": 80000,
        "settlementPeriodSalary": "perYear",
        "holidaysPerYear": 24,
        "workingHoursPerWeek": 40,
        "probationPeriod": "6Months",
        "noticePeriodDuringProbation": "4Weeks",
        "noticePeriodDuringProbationStart": "endOfWeek"
    },
    "workSchedule": {
        "scheduledDate": "2017-04-15",
        "days": [
            {
                "dayOfWeek": "MONDAY",
                "worktimeInMinutes": 380
            },
            {
                "dayOfWeek": "FRIDAY",
                "worktimeInMinutes": 360
            }
        ],
        "defaultSchedule": "TRUE"
    }
}

POST /employees/

Description: Add an employee to your company, and send an email for the employee to register with HeavenHR.

Parameters

Name	Description	Required	Schema
body	Employee to be added to the company	Yes	EmployeeCreatedRequest

Responses

Code	Description	Schema
201	The submitted employee has been created	CreateEmployeeResponse
400	The submitted employee record is invalid	CreateEmployeeResponse
403	Invalid permissions. The key you are using is incorrect, or only has read access granted

Get a employee

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}' 

> The above command returns JSON structured like this:
{
    "startDate": "2017-04-13",
    "endOfContract": "2022-04-13",
    "professionalEmail": "professionalEmail@heavenhr.de",
    "jobTitle": "Head of Sales",
    "permanentOrTemporary": "PERMANENT",
    "streetPersonal": "Griefwalderstrasse",
    "streetNumberPersonal": 219,
    "additionalContractInformation": "The employee has the right to take leave 24 days a year.",
    "locationId": "_bE1Zi2WRANH76y0vDbdEdA_",
    "employeeNumber": 716,
    "gender": "MALE",
    "nationality": "DE",
    "occupation": "Manager",
    "firstName": "Max",
    "fullTimeOrPartTime": "FULL_TIME",
    "employmentType": "FREELANCER",
    "lastName": "Musterman",
    "jobStatus": "CREATED_EXISTING",
    "mobileWork": 63121,
    "dateOfBirth": "1984-07-17",
    "departmentId": "_EaH3L12VPSVhuSDPqkKIdg_",
    "phonePersonal": 4921348182,
    "costCenterId": "_3q4nkYvIocIJDUhyZJh5dQ_",
    "email": "email@heavenhr.de",
    "sendOnboardingEmail": true,
    "customAttributes": [
       {
        "id": "_Aeqew@adq3dsfADRaqw",
        "name": "Customer attribute Name",
        "value": "I am superman"
       }
    ],
    "contract": {
        "grossSalary": 80000,
        "settlementPeriodSalary": "perYear",
        "holidaysPerYear": 24,
        "workingHoursPerWeek": 40,
        "probationPeriod": "6Months",
        "noticePeriodDuringProbation": "4Weeks",
        "noticePeriodDuringProbationStart": "endOfWeek"
    },
    "workSchedule": {
        "scheduledDate": "2017-04-15",
        "days": [
            {
                "dayOfWeek": "MONDAY",
                "worktimeInMinutes": 480
            },
            {
                "dayOfWeek": "FRIDAY",
                "worktimeInMinutes": 360
            }
        ],
        "defaultSchedule": "TRUE"
    }
}

Description: Find employee by ID and return all the employee details

GET /employees/{id}

Parameters

Name	Description	Required	Schema
id	The ID of employee to return	Yes	string

Responses

Code	Description	Schema
200	Success	Employee
400	Invalid ID supplied
404	Employee not found

Update a employee

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id} -X PATCH' 

> The above command returns JSON structured like this:

{
    "startDate": "2017-04-13",
    "endOfContract": "2022-04-13",
    "professionalEmail": "professionalEmail@heavenhr.de",
    "jobTitle": "Head of Sales",
    "permanentOrTemporary": "PERMANENT",
    "streetPersonal": "Griefwalderstrasse",
    "streetNumberPersonal": 219,
    "additionalContractInformation": "The employee has the right to take leave 24 days a year.",
    "locationId": "_bE1Zi2WRANH76y0vDbdEdA_",
    "employeeNumber": 716,
    "gender": "MALE",
    "nationality": "DE",
    "occupation": "Manager",
    "firstName": "Max",
    "fullTimeOrPartTime": "FULL_TIME",
    "employmentType": "FREELANCER",
    "lastName": "Musterman",
    "jobStatus": "CREATED_EXISTING",
    "mobileWork": 63121,
    "dateOfBirth": "1984-07-17",
    "departmentId": "_EaH3L12VPSVhuSDPqkKIdg_",
    "phonePersonal": 4921348182,
    "costCenterId": "_3q4nkYvIocIJDUhyZJh5dQ_",
    "email": "email@heavenhr.de",
    "sendOnboardingEmail": true,
    "customAttributes": [
       {
        "id": "_Aeqew@adq3dsfADRaqw",
        "name": "Customer attribute Name",
        "value": "I am superman"
       }
    ],
    "contract": {
        "grossSalary": 80000,
        "settlementPeriodSalary": "perYear",
        "holidaysPerYear": 24,
        "workingHoursPerWeek": 40,
        "probationPeriod": "6Months",
        "noticePeriodDuringProbation": "4Weeks",
        "noticePeriodDuringProbationStart": "endOfWeek"
    },
    "workSchedule": {
        "scheduledDate": "2017-04-15",
        "days": [
            {
                "dayOfWeek": "MONDAY",
                "worktimeInMinutes": 480
            },
            {
                "dayOfWeek": "FRIDAY",
                "worktimeInMinutes": 360
            }
        ],
        "defaultSchedule": "TRUE"
    }
}

PATCH /employees/{id}

Description: Update the details of a specific employee. This will only update the fields that are sent, including fields for Contract and WorkSchedule

Parameters

Name	Description	Required	Schema
id	The ID of employee to update	Yes	string

Responses

Code	Description	Schema
204	Success	EmployeeUpdate
400	Invalid ID supplied
404	Employee not found

Get all employees

curl 'https://api.heavenhr.com/api/v2/employees/ -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 200,
    "totalItems": 23,
    "totalPages": 1,
    "data": [
        {
            "id": "_CNr_06hxMX3DXdrkbY4FQw_",
            "firstName": "aaaaa First Name",
            "lastName": "aaaaa last Name",
            "employeeNumber": 1,
            "jobStatus": "CREATED_EXISTING",
            "updatedAt": "2018-09-25T12:17:26.522",
            "departmentName": "IT",
            "departmentId": null,
            "email": "nonexisting@aadas.com"
        },
        {
            "id": "_QU3zYEuk2WPclWSMv7vJQw_",
            "firstName": "bbbb First Name",
            "lastName": "last Name",
            "employeeNumber": 3,
            "jobStatus": "HIRED",
            "updatedAt": "2018-09-25T12:18:17.059",
            "departmentName": "Sales",
            "departmentId": null,
            "email": "donotreply@aadas.com"
        }
     ]
}

Find all employees in a sorted, paginated list by zero or more of the specified filters and return with limited fields

GET /employees

Description: Returns a list of employees with limited fields

Parameters

Name	Description	Required	Schema
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page	No	integer
employeeNumber	Returns the employee with this employee number	No	string
departmentId	Returns all employees with this department id	No	string
jobStatus	The status of employee	No	string
startDate	Returns all employees with this start date	No	dateTime
updatedAt	Returns all employees that have been updated since this time	No	dateTime in format of ISO DateTime Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ, e.g. “2000-10-31T01:30:00.000-05:00”.

Responses

Code	Description	Schema
200	Success	PagedEmployeeResponse
404	No employees found (for this page)

Create Absence budget for an Employee

curl 'https://api.heavenhr.com/api/v2/employees/{id}/absencebudgets -X POST' -d '{"year":2018}'

Description: Create the budget for absence for a particular employee

Parameters

Name	Description	Required	Schema
id	The ID of employee to update	Yes	string

Create time tracking Request

curl 'https://api.heavenhr.com/api/v2/employees/{id}/timetracking -X POST ' 

{
  "projectId" : "_3PSTCjfM7B2qg5Az6wuRVg_",
  "startDate": "2019-10-24",
  "endDate": "2019-10-24",
  "startTime": "09:50", 
  "endTime": "18:55",
  "total" : "",
  "breakTime" : "30",
  "comment" : "",
  "status" : "REQUESTED",
  "categories": [
      "_xelst4ASGYOfEf30Qr_bMQ_",
      "_bJunkaJUb68E-Yn7y5ya6Q_"
    ]
}

POST /employees/{id}/timetracking

Description: Add new time tracking request to an Employee. the allowed status while creation are EDITABLE, REQUESTED.

Parameters

Name	Description	Required	Schema
body	Time Tracking Request for Employee	Yes	TimeTrackingCreateRequest

Responses

Code	Description	Schema
201	The submitted Time tracking request has been created	TimeTrackingCreateResponse
400	The submitted Time tracking request is invalid
403	Invalid permissions. The key you are using is incorrect, or only has read access granted

Update time Tracking Request

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking/{id} -X PATCH' 

{
  "projectId" : "_3PSTCjfM7B2qg5Az6wuRVg_",
  "startDate": "2019-10-24",
  "endDate": "2019-10-24",
  "startTime": "08:00",
  "endTime": "17:30",
  "total": 510,
  "breakTime" : 30,
  "comment" : "Time tracking request #1",
  "categories": [
      "_xelst4ASGYOfEf30Qr_bMQ_"
    ]
}

PATCH employees/{employee_id}/timetracking/{id}

Description: Update the details of a specific time Tracking Request. This will only update the fields that are sent,

Parameters

Name	Description	Required	Schema
employee_id	The owner employee Id of the time tracking request.	Yes	string
id	the ID of the time Tracking request to be updated.	Yes	string
status	the target time tracking status	Yes	TimeTrackingStatus

Responses

Code	Description	Schema
200	Success
400	Invalid ID supplied
404	Employee not found

Update the status of time Tracking Request

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking/{id}/{status} -X PATCH' 

PATCH employees/{employee_id}/timetracking/{id}/{status}

Description: Update the status of the request to one of the following values: REQUESTED, APPROVED, REJECTED.

Parameters

Name	Description	Required	Schema
employee_id	The owner employee Id of the time tracking request.	Yes	string
id	the ID of the time Tracking request to be updated.	Yes	string
status	the target time tracking status	Yes	TimeTrackingStatus

Responses

Code	Description	Schema
200	Success
400	Invalid ID supplied
404	Employee or time tracking request not found

Get Time tracking request

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking/{id}' 

> The above command returns JSON structured like this:
{
  "projectId" : "_3PSTCjfM7B2qg5Az6wuRVg_",
  "requestDate":"2019-10-24",
  "status" : "REQUESTED",
  "startTime":"09:50",  
  "endTime":    "18:55",
  "totalTimeInMinutes" :    "",
  "breakTimeInMinutes" : "30",
  "comment" : "",
  "categories": [
    "_xelst4ASGYOfEf30Qr_bMQ_",
    "_bJunkaJUb68E-Yn7y5ya6Q_"
  ]
}

Description: Get time tracking request for employee by ID.

GET /employees/{employee_id}/timetracking/{id}

Parameters

Name	Description	Required	Schema
employee_id	The owner employee Id of the time tracking request.	Yes	string
id	the id of the requested time Tracking	Yes	string

Responses

Code	Description	Schema
200	Success	TimeTracking
404	Employee not found or Request Id Not Found

Get employees' time tracking requests

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking -X GET' 

> The above command returns JSON structured like this:

{
    "links": [],
    "data": [
        {
            "id": "_vnU2kfgMtfJlNApQm0uZdw_",
            "employeeId": "_3PSTCjfM7B2qg5Az6wuRVg_",
            "projectId": null,
            "requestDate": "2019-09-25",
            "startTime": "09:50",
            "endTime": "24:00",
            "totalTimeInMinutes": 790,
            "breakTimeInMinutes": 60,
            "comment": "",
            "status": "APPROVED",
            "categories": [
                {
                    "id": "_xelst4ASGYOfEf30Qr_bMQ_",
                    "name": "new category",
                    "status": "ACTIVE"
                }
            ]
        }
    ],
    "meta": {
        "page": 0,
        "pageSize": 1,
        "count": 1
    }
}

Find all employees's time tracking requests in a sorted, paginated list by zero or more of the specified filters

GET /employees/{employee_id}/timetracking

Description: Returns a list of employees' time tracking requests with limited fields

Parameters

Name	Description	Required	Schema
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page	No	integer
status	the time tracking request status to filter with	No	string
requestDate	the time tracking request start date to filter with	No	string

Responses

Code	Description	Schema
200	Success	PagedTimeTrackingRequest
404	No time tracking requests found for the given employee Id

Get Time tracking projects

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking/projects' 

> The above command returns JSON structured like this:
{
    "id": "_t22XLGQkdeRvWb1JK_RTMA_",
    "name": "testing ",
    "status": "ACTIVE"
}

Description: Get time tracking request for employee.

GET /employees/{employee_id}/timetracking/projects

Parameters

Name	Description	Required	Schema
employee_id	The employee Id to list the projects for.	Yes	string

Responses

Code	Description	Schema
200	Success	Project List
404	Employee not found

Get all shifts for an employee

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/shifts' -X GET 

> The above command returns JSON structured like this:
{
    "page": 0,
    "pageSize": 200,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
       {
          "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
          "startTime": "2019-01-02T08:00:00",
          "endTime": "2019-01-02T17:00:00",
          "status": "PUBLISHED"
       },
       {
          "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
          "startTime": "2019-01-03T08:00:00",
          "endTime": "2019-01-03T17:00:00",
          "status": "DRAFT"
       }
    ]
}

Description: Get all shifts for an employee

GET /employees/{employee_id}/shifts/

Parameters

Name	Description	Required	Schema
employee_id	The employee Id to get all shifts	Yes	string
startDate	Start date for search	Yes	ISO Date Format: yyyy-MM-dd
endDate	End date for search	Yes	ISO Date Format: yyyy-MM-dd

Responses

Code	Description	Schema
200	Success	PagedShiftResponse
404	Employee not found

Company Information

Get Company info

curl 'https://api.heavenhr.com/api/v2/company/ -X GET' 

{
    "links": [],
    "data": [
        {
            "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
            "name": "Awesome HR company",
            "customAttributes": [
                {
                    "id": "_9X8jV4qypU6As7SlyBtT8w_",
                    "name": "test attribute",
                    "type": "STRING",
                    "category": "PERSON_BASIC_DATA"
                }
            ]
        }
    ]
}

Description: Returns the company info. This API also returns the custom Attributes defined. The ID of the customAttributes is used for creating/updating the employees with the value.

Parameters

Responses

Code	Description	Schema
200	Success	CompanyResponse

Get Organizations

curl 'https://api.heavenhr.com/api/v2/company/organizations -X GET' 

> The above command returns JSON structured like this:

{
  "data": [
    {
      "headsOfUnit": null,
      "pathName": "HeavenHR",
      "children": [
        null
      ],
      "name": "HeavenHR",
      "id": "_WBMlOvhvkQ-7ABKJ9aK4Nw_"
    }
  ],
}   ]
}

Traverse the hierarchical structure of a company Get /company/organizations

Description: Returns the company structure tree

Responses

Code	Description	Schema
200	Success	PagedOrganizationResponse
404	No company organization structure information found (for this page)

Get locations

curl 'https://api.heavenhr.com/api/v2/company/locations -X GET' 

> The above command returns JSON structured like this:

{
  "totalItems": 1,
  "totalPages": 1,
  "data": [
    {
      "city": "Berlin",
      "id": "_WBMlOvhvkQ-7ABKJ9aK4Nw_",
      "name": "Berlin Office",
      "country": "Germany"
    }
  ],
  "page": 0,
  "pageSize": 0
}

Find all locations for a company

GET /company/locations

Description: Returns a list of locations

Parameters

Name	Located in	Description	Required	Schema
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page	No	integer

Responses

Code	Description	Schema
200	Success	PagedLocationResponse
404	No location information found (for this page)

Get costcenters

curl 'https://api.heavenhr.com/api/v2/company/cost-centers -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 200,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "id": "_Lg9ISEggCDLw9Lj6motG1Q_",
            "number": "1485",
            "name": "Marketing",
            "employeeCount": 5
        },
        {
            "id": "_84_UGt4Ljku6i7Ka15XO1Q_",
            "number": "1359",
            "name": "Sales",
            "employeeCount": 7
        }
    ]
}

Find all the cost centers for a company

GET /company/cost-centers

Description: Returns a list of cost centers

Parameters

Name	Located in	Description	Required	Schema
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page	No	integer

Responses

Code	Description	Schema
200	successful operation	PagedCostCenterResponse
404	No cost center information found (for this page)

Get detailed shift

curl 'https://api.heavenhr.com/api/v2/company/shifts/{shift_id}' -X GET 

> The above command returns JSON structured like this:
{
  "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
  "breakInMinutes": 60, 
  "totalInMinutes": 480,
  "type": {
     "id": "_5Q8jY0qypU3Fs7PlyUtJ3w_",
     "name": "Day Shift",
     "status": "ACTIVE"
  },
  "startTime": "2019-01-02T08:00:00",
  "endTime": "2019-01-02T17:00:00",
  "assignedUsers": [
     "_xQfoTYosQrl3WKzjFg431A_",
     "_7qPbfSo-b_0HMtPK7o7wdg_"
  ],
  "status": "PUBLISHED",
  "orgaUnits": [
    "_bE1Zi2WRANH76y0vDbdEdA_"
  ],
  "occupations": [ 
    {
      "name": "Hoster",
      "count": 3
    } 
  ],
  "shortHanded": false 
}

Description: Get detailed shift

GET /company/shifts/{shift_id}

Parameters

Name	Description	Required	Schema
shift_id	The shift Id desired.	Yes	string

Responses

Code	Description	Schema
200	Success	ShiftDetail
404	Shift not found

Get shifts

curl 'https://api.heavenhr.com/api/v2/company/shifts' -X GET 

> The above command returns JSON structured like this:
{
    "page": 0,
    "pageSize": 200,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
       {
          "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
          "startTime": "2019-01-02T08:00:00",
          "endTime": "2019-01-02T17:00:00",
          "assignedUsers": [
            "_xQfoTYosQrl3WKzjFg431A_",
            "_7qPbfSo-b_0HMtPK7o7wdg_"
          ],
          "status": "PUBLISHED"
       },
       {
          "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
          "startTime": "2019-01-03T08:00:00",
          "endTime": "2019-01-03T17:00:00",
          "assignedUsers": [
            "_xQfoTYosQrl3WKzjFg431A_",
            "_7qPbfSo-b_0HMtPK7o7wdg_",
            "_IV8VZcWICnD_NV4aFJuZig_"
          ],
          "status": "DRAFT"
       }
    ]
}

Description: Returns a list of shifts

GET /company/shifts/

Parameters

Name	Description	Required	Schema
startDate	Start date for search	Yes	ISO Date Format: yyyy-MM-dd
endDate	End date for search	Yes	ISO Date Format: yyyy-MM-dd
status	The status of the shift. Default value is PUBLISHED	No	string Values: DRAFT or PUBLISHED

Responses

Code	Description	Schema
200	Success	PagedShiftCompanyResponse
403	Invalid permissions. The key you are using is incorrect, or only has read access granted

Get categories

curl 'https://api.heavenhr.com/api/v2/company/timetracking/categories' -X GET 

> The above command returns JSON structured like this:
{
    "page": 0,
    "pageSize": 200,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "id": "_xelst4ASGYOfEf30Qr_bMQ_",
            "name": "new category",
            "status": "ACTIVE"
        },
        {
            "id": "_bJunkaJUb68E-Yn7y5ya6Q_",
            "name": "neu Kategorie",
            "status": "ACTIVE"
        }
    ]
}

Description: Returns a list of categories for time tracking

GET company/timetracking/categories

Parameters

Name	Located in	Description	Required	Schema
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page	No	integer

Responses

Code	Description	Schema
200	Success	PagedCategoriesResponse
403	Invalid permissions. The key you are using is incorrect, or only has read access granted

Payroll

Get Company Payroll Periods

curl 'https://api.heavenhr.com/api/v2/payroll/payrollperiod -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 1000,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "id": "_WBMlOvhvkQ-7ABKJ9aK4Nw_",
            "dateStart": "2018-04-01",
            "dateEnd": "2018-04-30",
            "status": "OPEN"
        },
        {
            "id": "_fGoS4__ElNagsberYKfYJQ_",
            "dateStart": "2018-03-01",
            "dateEnd": "2018-03-31",
            "status": "CLOSED"
        }
    ]
}

GET /payroll/payrollperiod

Description: Get all the payroll periods for a company, the current and the closed

Parameters

Name	Description	Required	Schema
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page	No	integer

Responses

Code	Description	Schema
200	Successful operation	PagedPayrollPeriodResponse
403	Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Get Sub Company Payroll Periods

curl 'https://api.heavenhr.com/api/v2/payroll/{subcompany_id}/payrollperiod -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 1000,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "id": "_fGoS4__ElNniBaWsEKfYJQ_",
            "dateStart": "2018-04-01",
            "dateEnd": "2018-04-30",
            "status": "OPEN"
        },
        {
            "id": "_9X8jV4qypU6As7SlyBtT8w_",
            "dateStart": "2018-03-01",
            "dateEnd": "2018-03-31",
            "status": "CLOSED"
        }
    ]
}

GET /payroll/{subcompany_id}/payrollperiod

Description: Get all the payroll periods for a sub company, the current and the closed

Parameters

Name	Description	Required	Schema
subcompany_id	The ID of the sub company	Yes	string
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page	No	integer

Responses

Code	Description	Schema
200	Successful operation	PagedPayrollPeriodResponse
403	Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Get Payroll Period Salary Details

curl 'https://api.heavenhr.com/api/v2/payroll/payrollperiod/{payrolperiod_id}/salary -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 1000,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "employeeId": "_dK4xhpkYvXCjlMcmppVRdg_",
            "firstName": "Max",
            "lastName": "Musterman",
            "personelNumber": "1001",
            "salary": {
                "fixedSalary": 1500000000,
                "others": 301
            }
        },
        {
            "employeeId": "_rT6xhpkPvYBjlZcrhgQAfw_",
            "firstName": "Fernanda",
            "lastName": "Fructuoso",
            "personelNumber": "1002",
            "salary": {
                 "fixedSalary": 1600000000,
                 "others": 400
            }
        }
    ]
}

GET /payroll/payrollperiod/{payrollperiod_id}/salary

Description: Get all the salary details for a payroll period

Parameters

Name	Description	Required	Schema
payrolperiod_id	The ID of the payroll period	Yes	string
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page	No	integer

Responses

Code	Description	Schema
200	Successful operation	PagedPayrollPeriodSalaryDetailsresponse
403	Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation
404	No payroll period found for the given ID

Recruiting

Get Vacancy

curl 'https://api.heavenhr.com/api/v1/positions/public/vacancies/{vacancy_id} -X GET' 

> The above command returns JSON structured like this:

{
    "data": [
        {
            "id": "_c4mWzU4vUb_U6PV0yxQl_g_",
            "jobTitle": "Head of Sales",
            "description": "<p>Position to be the Head of our sales department.</p>",
            "employmentTypes": [
                "FULL_TIME"
            ],
            "numberOfOpenings": 1,
            "location": "Brussles",
            "department": "Sales",
            "publicationDate": "2019-02-11",
            "numberOfApplicants": 0,
            "companyId": "_Jn4W-x3rvGß0Rk-CwYUYYA_",
            "status": "PUBLISHED",
            "industry": "TELECOMMUNICATIONS",
            "fieldOfWork": "SERVICE",
            "positionType": "MANAGER",
            "seniority": "SENIOR",
            "employmentStartDate": "2019-06-11",
            "hiringOrganization": "Company Z4",
            "qualifications": "<p>Masters Degrees in Sales Management</p>",
            "responsibilities": "<p>Entire department<p>",
            "incentives": "<p>Bus ticket<p>",
            "contact": "contact info goes here"
        }
    ]
}

GET /positions/public/vacancies/{vacancy_id}

Description: Find vacancy by ID and return all the vacancy details

Parameters

Name	Description	Required	Schema
vacancy_id	The ID of the vacancy	Yes	string

Responses

Code	Description	Schema
200	Successful operation	PublicVacancy
403	Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation
404	No vacancy found for the given ID

Get All Vacancies

curl 'https://api.heavenhr.com/api/v1/positions/public/vacancies/ -X GET' 

> The above command returns JSON structured like this:
{
    "data": [
        {
            "id": "_rW4JzrNQIs8LuqHXliwlaA_",
            "email": "new@email.com",
            "jobTitle": "Full-stack web developer",
            "employmentTypes": [
                "FULL_TIME"
            ],
            "location": "Paris",
            "department": "IT",
            "publicationDate": "2019-01-03",
            "status": "PUBLISHED",
            "industry": "PRINT MEDIA",
            "fieldOfWork": "SERVICE",
            "positionType": "FULL-TIME",
            "seniority": "MANAGER",
            "employmentStartDate": "2019-07-01",
            "hiringOrganization": "<p>Company X</p>",
            "qualifications": "<p>Java 8</p>",
            "responsibilities": "<p>Code, test, deploy</p>",
            "incentives": "<p>free coffee</p>",
            "contact": "contact information goes here"
        },
        {
            "id": "_S2fzaC9XFKXrqy9adYBLGg_",
            "email": "new@email.com",
            "jobTitle": "Sales Manager",
            "employmentTypes": [
                "FULL_TIME"
            ],
            "location": "Brussles",
            "department": "Marketing and Sales",
            "publicationDate": "2019-03-11",
            "status": "PUBLISHED",
            "industry": "TELECOMMUNICATIONS",
            "fieldOfWork": "SERVICE",
            "positionType": "MANAGER",
            "seniority": "SENIOR",
            "employmentStartDate": "2019-03-11",
            "hiringOrganization": "Company X",
            "qualifications": "<p>Masters Degrees in Sales Management</p>",
            "responsibilities": "<p>Entire department</p>",
            "incentives": "<p>Bus ticket</p>",
            "contact": "contact information goes here"
        }
    ]
}

GET /positions/public/vacancies/

Description: Find all the vacancy according of the required parameters

Parameters

Name	Description	Required	Schema
companyId	Your company ID	Yes	string
sortBy		No	string
page	The current page number. Zero-indexed, so the first page is 0	No	integer
pageSize	How many items are in each page. Default value is 10	No	integer

Responses

Code	Description	Schema
200	Successful operation	PublicVacancy
403	Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Vacation & Absence

---

Get Vacation and Absence Types

curl 'https://api.heavenhr.com/api/v2/company/absences/types -X GET' 

> The above command returns JSON structured like this:

{
    "data": [
        {
            "typeId": "1",
            "type": "Urlaub",
            "vacationType": "HOLIDAY",
            "colorCode": "#cddc39",

        },
        {
            "typeId": "2",
            "type": "Unbezahlter Urlaub",
            "vacationType": "UNPAIDLEAVE",
            "colorCode": "#fdd835",

        },
    ],

}

GET company/absences/types/

Description: Find all the absence types for the company.

Parameters

Name	Description	Required	Schema

Responses

Code	Description	Schema
200	Successful operation	AbsenceType
403	Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Get Company Vacations and Absences

curl 'https://api.heavenhr.com/api/v2/company/absences?page=0&pageSize=100&startDate=2019-07-01&endDate=2019-07-30&status=REJECTED,APPROVED -X GET' 

> The above command returns JSON structured like this:

{
    "data": [
        {
            "employeeId": "1",
            "firstName": "Jurgen",
            "lastName": "Klopp",
            "startDate": "2019-07-01",
            "endDate": "2019-07-07",
            "budgetUsed": true,
            "numberOfDays": 5,
            "absenceType": "ILLNESS",
            "status": "APPROVED",
            "exceedBudget": false,
            "departmentId": 1,
            "comments": [
                {
                    "companyId": "1",
                    "ownerId": "1",
                    "ownerType": "ABSENCE_REQUEST",
                    "userId": "1",
                    "userFullName": "Admin",
                    "text": "this is a sample comment\n",
                    "creationDate": "2019-06-13T12:58:12.152"
                }
            ],

        }
    ],
    "meta": {
        "page": 0,
        "pageSize": 1,
        "count": 1
    },

}

GET company/absences/

Description:

Parameters

Name	Description	Required	Schema
startDate	Start date	Yes	Format is YYYY-MM-DD
endDate	End date	Yes	Format is YYYY-MM-DD
status	One or more of these statuses. PLANNED, REQUESTED, APPROVED, REJECTED, WITHDRAWN	Yes
page	The current page number. Zero-indexed, so the first page is 0	Yes	integer
pageSize	How many items are in each page. Default value is 10	Yes	integer

Responses

Code	Description	Schema
200	Successful operation	AbsenceRecord
403	Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Get Employee Vacations and Absences

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/absences/?page=0&pageSize=100&startDate=2019-07-01&endDate=2019-07-30&status=REJECTED,APPROVED -X GET' 

> The above command returns JSON structured like this:

{
    "data": [
        {
            "employeeId": "1",
            "firstName": "Jurgen",
            "lastName": "Klopp",
            "startDate": "2019-07-01",
            "endDate": "2019-07-07",
            "budgetUsed": true,
            "numberOfDays": 5,
            "absenceType": "ILLNESS",
            "status": "APPROVED",
            "exceedBudget": false,
            "departmentId": 1,
            "comments": [
                {
                    "companyId": "1",
                    "ownerId": "1",
                    "ownerType": "ABSENCE_REQUEST",
                    "userId": "1",
                    "userFullName": "Admin",
                    "text": "this is a sample comment\n",
                    "creationDate": "2019-06-13T12:58:12.152"
                }
            ],

        }
    ],
    "meta": {
        "page": 0,
        "pageSize": 1,
        "count": 1
    },

}

GET employees/{employee_id}/absences/

Description: Find all the absences and vacations for the employee according to the provided parameters.

Parameters

Name	Description	Required	Schema
employeeId	Employee Id	Yes	string
startDate	Start date Format is YYYY-MM-DD	Yes	date
endDate	End date Format is YYYY-MM-DD	Yes	date
status	One or more of these statuses. PLANNED, REQUESTED, APPROVED, REJECTED, WITHDRAWN	Yes	string
page	The current page number. Zero-indexed, so the first page is 0	Yes	integer
pageSize	How many items are in each page. Default value is 10	Yes	integer

Responses

Code	Description	Schema
200	Successful operation	AbsenceRecord
403	Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Models

---

EmployeeCreated

Name	Type	Description	Required
id	string		No
email	string		Yes

EmployeeUpdate

Name	Type	Description	Required
gender	string		No
professionalEmail	string	The professional email of the employee	No
email	string	The private email of the employee	No

EmployeeSimple

Name	Type	Description	Required
id	string		No
firstName	string		No
lastName	string		No
employeeNumber	string		No
jobStatus	string		No
updatedAt	dateTime		No
departmentName	string		No
departmentId	string		No
email	string		Yes

EmployeeCreatedRequest

Name	Type	Description	Required
gender	string		No
professionalEmail	string		No
email	string		Yes
firstName	string		Yes
lastName	string		Yes
phonePersonal	string		No
mobileWork	string		No
streetPersonal	string	Home address street	No
streetNumberPersonal	string	Home address number	No
dateOfBirth	date	Format is YYYY-MM-DD	No
nationality	string		No
additionalContractInformation	string	This field is a free text field for any comments on the contract.	No
employeeNumber	string	This is a unique employee number	No
jobStatus	string		No
jobTitle	string		No
occupation	string		No
locationId	string	This is the id of the location from the endpoint /company/locations	Yes
permanentOrTemporary	string	This is whether the employee is fixed contract or has a temporary contract	No
employmentType	string		No
startDate	date	Format is YYYY-MM-DD	No
endOfContract	date	Format is YYYY-MM-DD	No
fullTimeOrPartTime	string		No
costCenterId	string	The id of the cost centre the employee belongs to. This is the id from the endpoint /company/cost-centers	No
departmentId	string	The id of the department the employee belongs to. This is the id from the /company/organizations	No
sendOnboardingEmail	boolean	If you want to send onboarding email for the employee, default is False	No
customerAttributes	Array	Custom attributes defined for employees on company level	No
contract	Contract	Contract details for the employee	No
workSchedule	WorkSchedule	Create a work schedule for the employee	No

CreateEmployeeResponse

Name	Type	Description	Required
errors	[ object ]		No
employee	EmployeeCreated		No

PagedEmployeeResponse

Name	Type	Description	Required
page	integer		No
pageSize	integer		No
totalItems	long		No
totalPages	integer		No
data	[ EmployeeSimple ]		No

CompanyResponse

Name	Type	Description	Required
id	string		No
name	string		No
customAttributes	[ CustomAttributes ]		No

CustomAttributes

Name	Type	Description	Required
id	string		No
name	string		No
type	string		No
category	string		No

Organization

Name	Type	Description	Required
id	string		No
name	string		No
pathName	string		No
headsOfUnit	[ string ]		No
children	[ Organization ]		No

PagedOrganizationResponse

Name	Type	Description	Required
page	integer		No
pageSize	integer		No
totalItems	long		No
totalPages	integer		No
data	[ Organization ]		No

Location

Name	Type	Description	Required
id	string		No
name	string		No
city	string		No
country	string		No

PagedLocationResponse

Name	Type	Description	Required
page	integer		No
pageSize	integer		No
totalItems	long		No
totalPages	integer		No
data	[ Location ]		No

CostCenter

Name	Type	Description	Required
id	string		No
name	string		No
number	string		No
employeeCount	integer		No

PagedCostCenterResponse

Name	Type	Description	Required
page	integer		No
pageSize	integer		No
totalItems	long		No
totalPages	integer		No
data	[ CostCenter ]		No

TimeTrackingCreateRequest

Name	Type	Description	Required
projectId	string	time tracking project Id	No
startDate	string	Request Start Date	Yes
endDate	string	Request End Date	Yes
startTime	string		Yes
endTime	string		Yes
totalTimeInMinutes	string		No
breakTimeInMinutes	string		No
comment	string		No
status	string		No
categories	string	List of categories Ids	No

TimeTrackingCreateResponse

Name	Type	Description	Required
timeTracking	TimeTrackingCreateResponse		No

TimeTrackingRequest

Name	Type	Description	Required
id	string		Yes
projectId	string	time tracking project Id	No
requestDate	string	Request Date	Yes
startTime	string		Yes
endTime	string		Yes
totalTimeInMinutes	string		No
breakTimeInMinutes	string		No
comment	string		No
status	string	Request Status	Yes
categories	string	List of categories Ids	No

Projects

Name	Type	Description	Required
id	string	time tracking project id	Yes
name	string	time tracking project name	Yes
status	string	Project Status	Yes

TimeTrackingStatus

Name	Type	Description	Required
status	string	Time tracking Status has to be one of the following values REQUESTED, APPROVED, REJECTED	Yes

PagedTimeTrackingRequest

Name	Type	Description	Required
page	integer		No
pageSize	integer		No
count	integer		No
data	[ TimeTrackingRequest ]		No

Contract

Name	Type	Description	Required
grossSalary	double	Gross salary	Yes
settlementPeriodSalary	string	Settlement period for the salary	Yes
holidaysPerYear	string	Numbers of holidays per year	Yes
workingHoursPerWeek	string	Working hours per week	Yes
probationPeriod	string	Probation period duration	Yes
noticePeriodDuringProbation	string	Notice period during probation duration	Yes
noticePeriodDuringProbationStart	string		Yes

WorkSchedule

Name	Type	Description	Required
scheduledDate	date	Start date of the work schedule. Pattern: yyyy-MM-dd	Yes
days	Day	List of days for the work schedule	Yes
defaultSchedule	boolean	If is the default work schedule of the employee	No

Day

Name	Type	Description	Required
dayOfWeek	string	The day of the week	Yes
worktimeInMinutes	integer	Work time in minutes for the day	Yes

PayrollPeriodPagedResponse

Name	Type	Description	Required
page	integer	The current page number. Zero-indexed, so the first page is 0	No
pageSize	integer	How many items are in each page	No
totalItems	long	How many items were found in total	No
totalPages	integer	Total number of pages	No
data	[PayrollPeriod]	List of payroll periods	No

PayrollPeriod

Name	Type	Description	Required
id	string	Id of the payroll period	No
dateStart	date	The start date of the payroll period	No
dateEnd	date	The end date of the payrolld period	No
status	string	Status of the payroll period, status has one of the two values OPEN, CLOSED	No

PagedPayrollPeriodSalaryDetailsresponse

Name	Type	Description	Required
page	integer	The current page number. Zero-indexed, so the first page is 0	No
pageSize	integer	How many items are in each page	No
totalItems	long	How many items were found in total	No
totalPages	integer	Total number of pages	No
data	[SalaryDetails]	List of all salary detials for the payroll period	No

SalaryDetails

Name	Type	Description	Required
employeeId	string		No
firstName	string		No
personelNumber	string		No
salary	[Salary]	Salary details	No

Salary

Name	Type	Description	Required
fixedSalary	long		No
others	long		No

PagedShiftResponse

Name	Type	Description	Required
page	integer	The current page number. Zero-indexed, so the first page is 0	No
pageSize	integer	How many items are in each page	No
totalItems	long	How many items were found	No
totalPages	integer	The total number of pages	No
data	[Shift]	List of shifts	No

Shift

Name	Type	Description	Required
id	string	Id of the shift	Yes
startTime	dateTime	Date and time when the shift started	Yes
endTime	dateTime	Date and time when the shift ended	Yes
status	string	The status can be one of the two values DRAFT or PUBLISHED	Yes

PagedShiftCompanyResponse

Name	Type	Description	Required
page	integer	The current page number. Zero-indexed, so the first page is 0	No
pageSize	integer	How many items are in each page	No
totalItems	long	How many items were found	No
totalPages	integer	The total number of pages	No
data	[CompanyShift]	List of shifts	No

CompanyShift

Name	Type	Description	Required
id	string	Id of the shift	No
startTime	dateTime	Date and time when the shift started	No
endTime	dateTime	Date and time when the shift ended	No
assignedUsers	string	Assigned users Id list	No
status	string	The status can be one of the two values DRAFT or PUBLISHED	No

ShiftDetail

Name	Type	Description	Required
id	string	Id of the shift	No
breakInMinutes	long		No
totalInMinutes	long		No
type	[ShiftType]		No
startTime	dateTime	Date and time when the shift started	No
endTime	dateTime	Date and time when the shift ended	No
assignedUsers	string	Assigned users Id list	No
status	string	The status can be one of the two values DRAFT or PUBLISHED	No
orgaUnits	string	Ids of applicable organization units	No
occupations	[Occupation]	List of occupations	No
shortHanded	boolean	If the shift is short handed	No

ShiftType

Name	Type	Description	Required
id	string	Id of the type	No
name	string	Name of the shift type	No
status	string	Status has one of the following values ACTIVE, INACTIVE, ARCHIVED	No

Occupation

Name	Type	Description	Required
name	string	Name of the occupation	No
count	integer	Amount of the occupation	No

PagedCategoriesResponse

Name	Type	Description	Required
page	integer	The current page number. Zero-indexed, so the first page is 0	No
pageSize	integer	How many items are in each page	No
totalItems	long	How many items were found	No
totalPages	integer	The total number of pages	No
data	[Category]	List of categories	No

Category

Name	Type	Description	Required
id	string	Id of the category	No
name	string	Name of the category	No
status	string	Status has one of the following values ACTIVE, INACTIVE, ARCHIVED	No

PublicVacancyItem

Name	Type	Description	Required
id	string	Id of the category	No
email	string		No
jobTitle	string		No
employmentTypes	[EmploymentType]	A list of EmploymentType	No
location	string	The location of the vacancy	No
department	string	The department name	No
publicationDate	date		No
status	[VacancyStatus]	The status of the Vacancy	No
industry	[Industry]		No
fieldOfWork	[FieldOfwork]		No
positionType	[PositionType]		No
seniority	[Seniority]		No
employmentStartDate	date	The date the employee should start	No
hiringOrganization	string		No
qualifications	string		No
responsibilities	string		No
incentives	string		No
contact	string		No

PublicVacancy

Name	Type	Description	Required
id	string	Id of the public vacancy	No
jobTitle	string		No
description	string		No
employmentTypes	[EmploymentType]	A list of EmploymentType	No
numberOfOpenings	integer		No
location	string	The location of the vacancy	No
department	string	The department name	No
publicationDate	date		No
numberOfApplicants	integer		No
companyId	string		No
status	[VacancyStatus]	The status of the Vacancy	No
industry	[Industry]		No
fieldOfWork	[FieldOfwork]		No
positionType	[PositionType]		No
seniority	[Seniority]		No
employmentStartDate	date	The date the employee should start	No
hiringOrganization	string		No
qualifications	string		No
responsibilities	string		No
incentives	string		No
contact	string		No

EmploymentType

Name	Type	Description	Required
type	string	EmploymentType has one of the following values FULL_TIME, PART_TIME, CONTRACT, TEMPORARY, WORKING_STUDENT, INTERNSHIP, TRAINEE, FREELANCER, SHORT_TERM_EXTERNAL_LOAN, OTHER	No

VacancyStatus

Name	Type	Description	Required
status	string	VacancyStatus has one of the following values DRAFT, PUBLISHED, ARCHIVED	No

Industry

Name	Type	Description	Required
name	string	Type of the industry examples: Oil, It, Telecommunications	No

FieldOfwork

Name	Type	Description	Required
name	string	Field of work for the vacancy examples: Logistics, Law, Service, Sales	No

Seniority

Name	Type	Description	Required
name	string	The required seniority for the vacancy	No

AbsenceType

Name	Type	Description	Required
typeId	string	The id of the absence type	No
type	string	The type of absence	No
vacationType	string	The vacation type for the absence. HOLIDAY, UNPAIDLEAVE, OVERTIME, ILLNESS, SPECIALLEAVE	No
colorCode	string	Color code for the absence	No

AbsenceRecord

Name	Type	Description	Required
employeeId	string	The id of the employee	No
firstName	string	The first name of the employee	No
lastName	string	The last of the employee	No
startDate	date	The date when the absence was started	No
endDate	date	The date when the absence was ended	No
budgetUsed	double	Budget of the absences that was used for this absence	No
numberOfDays	double	Number of days of absence	No
absenceType	string	Type of absence	No
status	string	Status of the absence. PLANNED, REQUESTED, APPROVED, REJECTED, WITHDRAWN	No
comments	[Comment]	The comment for the absence	No
departmentId	string	Department id of the employee	No
exceedBudget	boolean	Budget was exceeeded or not for this absence	No

Comment

Name	Type	Description	Required
companyId	string	Company id for which comment was created	No
ownerId	string	Owner id of the comment	No
ownerType	string	Owner type of the comment	No
userId	string	User id of the user	No
userFullName	string	Name of the user who wrote this comment	No
text	string	Text of the comment	No
creationDate	date	The date when the comment was created	No

Errors

The HeavenHR API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The API requested is hidden for administrators only.
404	Not Found -- The specified entity could not be found.
405	Method Not Allowed -- You tried to access an API with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- You're requesting too many Information! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.