Request

This article explains the request header format for invoking HR Cloud APIs.

All APIs are accessible over HTTPS and support the standard HTTP methods. Each HTTP request mainly consists of the following four parts.

1. HTTP Method

2. URI

3. Request Headers

4. Request Body

HTTP Method

The request method indicates the operation to be performed on the resources identified by the given URI. The method is case-sensitive and should always be mentioned in uppercase. The following operations are supported.

 

Method Name Description
GET To retrieve a resource or its information
POST To create a new resource
PUT To update an existing resource
DELETE To delete an existing resource

URI

URI stands for Universal Resource Identifier and and identifies the resource on which the operation is to be performed.

All the APIs are accessible via the following URI:

https://corehr-api.hrcloud.com/:version/cloud/:resourceidentifier/:subresource

The following table explains the URI components.

 

URI Components Description
https Web protocol 
Basic passkey HTTP basic authentication credentials. You can alternatively use Customer_Key and Customer_Secret header values for authentication.
corehr-api.hrcloud.com The API endpoint domain.
version The version that is being requested. Currently limited to v1.
cloud Part of the endpoint domain that follows version.
resourceidentifier Identifier of the resource that is being requested (xEmployee, for example). 
subresource

A resource that is accessed in the scope of the parent resource.
For example, within the xEmployee entity you can use :employeeid to retrieve a specific employee.

Request Headers

Request Headers provide additional information about the requests and about the client to the server. Note the following points about the request headers:

  • For requests which contain data like POST and PUT requests, use:
    Content-type: application/json

    or

    Content-type: application/x-www-form-urlencoded
  • The Accept request-header is optional. If provided, it should be defined as application/json because that is the supported return format of the API:

    Http-accept: application/json
  • If using key and secret for authentication, pass the two as key value pairs along with the headers. For example, 
    Customer_Key 697ah89dc58a4
    Customer_Secret da2530cd0d024503e9a3
  • If using Basic authentication (username and password), generate a passkey using both the parameters and add to the authorization header. For example,
    passkey = EncodeToBase64(unencodedUsername +":"+unencodedPassword)
    authHeader = string.Format("{0} {1}", "Basic", passkey)
    request.Headers.Add("Authorization", authHeader);

 

A sample request message in Postman is as shown below:

GET /v1/cloud/xEmployee HTTP/1.1
Host: corehr-corehr-api.hrcloud.com
Content-Type: application/json
Customer_Key: 697ah89dc58a4
Customer_Secret: xYZsanbesdfetiomnsdfertsde2345sdX
Cache-Control: no-cache