Quick Start

Last updated: Dec 7th, 2017

Overview

HR Cloud's Employee API is a RESTful API that allows integration partners to create and update employee data—as well as associated entities such as departments, locations, and positions—in HR Cloud.

Once the Employee API has been enabled (see below), we suggest using Postman to get started on trying out some requests.

Authorization

Step One

To begin, navigate to the HR Cloud Integration API settings page and enable the APIs for your tenant.

HR Cloud Integrations API Settings

For integration partners, the HR Cloud Integrations APIs settings page should be enabled at the tenant level during implementation; however, if you do not see the "HR Cloud Integrations API" submenu item under the "Integrations" category, please, reach out for support.

Step Two

Once the APIs have been enabled, copy the authorization credentials provided for use in all HTTP requests. HR Cloud Integrations APIs use the HTTP Basic Authentication scheme so the base64-encoded string provided should be used at the value for the Authorization header in all API requests.

Screenshot from HR Cloud Integrations API Settings Page
screenshot
Example curl Request
                                        
curl -X POST \
    https://corehr.hrcloud.com/integrations/api/v1/employees \
    -H 'authorization: Basic MDFkYzMwMDktZDM2ZC00MWEyLTkyMTgtYmQxMGZlMTY1NGQyOjkyNTcyZjMxLTM0MWQtNDcwZi1iZDJkLWQ3NGNmZWM2MjYzYw==' \
    -H 'cache-control: no-cache' \
    -H 'content-type: application/json' \
    -d '[
        {
            #JSON payload ...
        },
]'

Employee API

Create or update employee records in HR Cloud.

Full URL:
https://corehr.hrcloud.com/integrations/api/v1/employees

All requests to this endpoint should use the POST request method for both creating and updating records.

JSON Body:
                                            
{
    "email": "employee@company.com",
    "firstName": "Employee",
    "lastName": "Employee",
    "startDate": "2018-01-17",
    "recordStatus": "Active",
    "accountType": "Employee",
    "employmentStatus": "Active",
    "employeeNumber": "company-1234-emp",
    "dateOfBirth": "2018-01-17",
    "managerEmail": "manager@company.com",
    "location": {
        "name": "LA Office",
        "code": "LA"
    },
    "department": {
        "name": "Research and Development",
        "code": "R&D"
    },
    "division": {
        "name": "Canada Division",
        "code": "CAN"
    },
    "position": {
        "name": "Software Engineer",
        "code": "SDE"
    },
    "address1": "1000 N Sepulveda Blvd",
    "address2": "Suite 1000",
    "city": "Los Angeles",
    "state": "California",
    "zipCode": "90034",
    "countryName": "United States"
}
API Responses
Action Status Body
Record Created 201 Created Empty
Record Updated 200 OK Empty
Field Details
Field Name Required Options Default Notes
email N/A N/A N/A
firstName N/A N/A N/A
lastName N/A N/A N/A
startDate N/A null N/A
recordStatus "Active", "Inactive" "Active" This field is case sensitive
accountType "Employee", "Admin" "Employee" This field is case senstive
employmentStatus "Active", "Leave of Absence", "Terminated" "Active" This field is case and space sensitive
employeeNumber N/A Autogenerated when null N/A
dateOfBirth N/A null N/A
managerEmail N/A null N/A
location* N/A Tenant default location is used when null name and code required when present
department* N/A Tenant default department is used when null name and code required when present
division* N/A Tenant default division is used when null name and code required when present
position* N/A Tenant default position is used when null name and code required when present
address1 N/A null N/A
address2 N/A null N/A
city N/A null N/A
state N/A null N/A
zipCode N/A null N/A
countryName N/A null Restricted to list from countries endpoint

Related Entities*

Entities related to employee—location, department, position, and division—are not required to create an employee record; however, if they are included in the JSON body of the request, they must contain both name and code or else the request will fail validation.

For all four entities, the value of code must be unique or else the request will fail validation. To update name, ensure code matches the value of the original entity and the value of name in the request will be applied to the extisting entity (e.g. to update the name "Los Angeles" to "Greater Los Angeles Area", ensure that the value of code on the update request matches that of the created entity, which in this example could be "code": "LA").

Supported Countries

Get the list of countries for your tenant.

Full URL
https://corehr.hrcloud.com/integrations/api/v1/countries

This endpoints supports the GET request method only.

JSON Body
                                            
[
    "United States",
    "Angola",
    "Canada",
    ...
]

Background Check API

The Background Check API allows tenants to integrate with their background check provider of choice by providing endpoints that accept background check report data on employees and report types offered by the third party provider. Additionally, a webhook with the background check provider allows users to request background checks as a part or upon completion of employee onboarding tasks.

Background Check Reports

Create or update background check report for employee.

Full URL:
https://corehr.hrcloud.com/integrations/api/v1/background-check-reports

All requests to this endpoint should use the POST request method for both creating and updating records.

JSON Body:
                                                
{
    "employeeEmail": "employee@company.com",
    "requestDateTime": "2018-02-15T11:00:00Z",
    "status": "Complete",
    "statusDateTime": "2018-03-17T11:00:00Z",
    "reportTypeName": "BASIC",
    "url": "https://vendor.site.com/reports/report-id-13"
}
API Responses
Action Status Body
Record Created 201 Created Empty
Record Updated 200 OK Empty
Field Details
Field Name Required Options Default Notes
employeeEmail N/A N/A Email identifier for report subject
requestDateTime N/A N/A Date/time report was requested
status N/A N/A Arbitrary string explaining report status
statusDateTime N/A N/A Date/time of report status change
reportTypeName N/A null Arbitrary string explaining report type
url N/A null Link to report record
Updating Background Check Reports

To update fields on the background check report, employeeEmail will be used to look up an existing report for update. Ensure that employeeEmail matches the report you're intending to update.

Background Check Report Types

Create or update background check report types.

Full URL:
https://corehr.hrcloud.com/integrations/api/v1/background-check-report-types

All requests to this endpoint should use the POST request method for both creating and updating records.

JSON Body:
                                                
[
    {
        "code": "BASIC_SCREENING",
        "name": "Basic worker background check"
    },
    {
        "code": "ENHANCED_SCREENING",
        "name": "Enhanced worker background check"
    }
]
API Responses
Action Status Body
Record Created 201 Created Empty
Record Updated 200 OK Empty

Report Types

Creating report types in HR Cloud is not required for initiating and completing background check tasks; however, once a list of report types has been created in HR Cloud, selecting a report type is required.

Request for Background Check Webhook

Request/initiate background check for employee with third party provider.

Full URL:
https://vendor.site.com/path-added-in-hrc-api-settnigs-page

HR Cloud will use the POST request method for both requesting/initiating background checks to the endpoint input in the HR Cloud Integration API settings page.

JSON Body:
                                                
{
    "employeeEmail": "employee@company.com",
    "requestDateTime": "2018-02-15T11:00:00Z",
    "reportTypeCode": "BASIC_SCREENING"
}
API Responses
Action Status Body
Record Created 201 Created Empty

Timeouts for Background Check Webhook

For any HTTP status other than 200 OK, the request to the webhook endpoint will timeout after ten seconds.

Each request will forcefully timeout after 10 seconds.

Errors

When there's an error procesing your request, the APIs will return a 400 Bad Request. The body of the response will contain an error code and description to help you identity the specific issue causing the request to fail. Below is a list of error codes you might encounter:

Employee API Error Codes and Descriptions 
                                            
[
    {
        "errorCode": "REQUIRED",
        "errorDescription": "[property name] is required"
    },
    {
        "errorCode": "INVALID_EMAIL",
        "errorDescription": "Email is invalid"
    },
    {
        "errorCode": "INVALID_VALUE",
        "errorDescription": "[value] is invalid"
    }
]

If you receive a 403 Forbidden, check that HR Integrations API has been enabled for your tenant. Also, given API users can choose to generate new authorization credentials, ensure that you update your request headers upon changing the credentials in the HR Cloud Integration API settings page.