Help Center

HR Cloud API

Employee

Employee - POST

This article explains the POST request to create an employee object.

Create a new employee

POST /xEmployee

Creates a new employee using the input parameters. If the request is successful , the newly created employee object information is returned in the response. On the other hand, if the request fails, an error message is returned in the response.

To create a new employee, add the following parameters in the request body in JSON format.

Please note that the response may contain additional employee fields like the Id. Any values (Optional fields) which are not provided in the request object are set to Null.

Input Parameters

Name	Type	Description	Is Mandatory
xFirstName	String	First name	Yes
xLastName	String	Last name	Yes
xFullName	String	Full name	Yes
xEmail	String	Email address	Yes
xEmployeeNumber	String	Unique employee number	Yes
xRecordStatus	String	Active or Inactive	Yes
xStartDate	Date	Start date	Yes
xAddress1	String	Address (street name and number)	No
xAddress2	String	Additional address information	No
xCity	String	City	No
xState	String	State	No
xZipCode	Number	Zip code	No
xCountry	Number	Country	No
xBonus	Json array	Bonus using two fields specifying amount and currency. Cannot be updated using PUT.	No
xCellPhone	String	Mobile phone number	No
xDateOfBirth	Date	Date of birth	No
xEducationLevel	String	Educational level	No
xEthnicity	String	Ethnicity	No
xGender	String	Female or Male	No
xInternationalTaxID	String	International tax ID	No
xMIddleName	String	MIddle name	No
xNickname	String	Nickname	No
xSalary	Json array	Salary using two fields specifying amount and currency. Cannot be updated using PUT.	No
xSeparationDate	Date	Separation (end) date	No
xSeparationReason	String	Separation reason	No
xSSN	String	Social security number	No
xVeteranStatus	String	Veteran status	No
xWorkPhone	String	Work phone number	No

You must also specify the following associated lookup data as parameters.

Name	Type	Description	Is Mandatory
xDepartmentLookup	String	Existing department ID	Yes
xEmploymentStatusLookup	String	Existing employment status ID	Yes
xLocationLookup	String	Existing location ID	Yes
xPositionLookup	String	Existing position ID	Yes
xDivisionLookup	String	Existing division ID	No
xEmploymentTypeLookup	String	Existing employment type ID	No
xManagerLookup	String	Existing manager ID	No

For example,

Request URL:

POST https://corehr-api.hrcloud.com/v1/cloud/xEmployee

Request Body:

{
    "xAddress1": "1498 Mill St.",
    "xCity": "Salem",
    "xEmail": "amanda@mytown.com",
    "xFirstName": "Amanda",
    "xFullName": "Amanda Jones",
    "xLastName": "Jones",
    "xPersonalEmail": "amanda51@hotmail.com",
    "xRecordStatus": "Active",
    "xStartDate": "2017-01-04T00:00:00Z",
    "xState": "OR",
    "xZipCode": "97165",
    "xEmployeeNumber": "7151641",
    "xEmploymentStatusLookup": "54ce3fe48ac9ebbf1869d52d43f715ef",
    "xLocationLookup": "16ed967dfe4607143cde66d04612c22a",
    "xPositionLookup": "8f72612cca4b41d4981d8dea2374f11f",
    "xDepartmentLookup": "a3a7aa7f8cfc7a46b78ce822d8da642a"
}

Response:

Status: 200 OK

[
    {
        "Id": "4e6f06d23efa2fb7536d96c2fb027feb",
        "xAddress1": "1498 Mill St.",
        "xAddress2": null,
        "xBonus": {
            "Amount": null,
            "Currency": null
        },
        "xCellPhone": null,
        "xCity": "Salem",
        "xCountry": null,
        "xCreatedOn": "2019-12-05T07:55:47.507Z",
        "xDateOfBirth": null,
        "xDepartmentLookup": {
            "__ObjectName": "xDepartment",
            "__Self": "https://corehr-api.hrcloud.com/v1/cloud/xDepartment/a3a7aa7f8cfc7a46b78ce822d8da642a",
            "Id": "a3a7aa7f8cfc7a46b78ce822d8da642a",
            "xDepartmentCode": "6cdcd962-ca3a-4707-afe1-6fb80def416d",
            "xDepartmentName": "Development",
            "xRecordStatus": "Active"
        },
        "xDivisionLookup": null,
        "xEducationLevel": null,
        "xEmail": "amanda@mytown.com",
        "xEmployeeNumber": "7151641",
        "xEmploymentStatusLookup": {
            "__ObjectName": "xEmploymentStatus",
            "__Self": "https://corehr-api.hrcloud.com/v1/cloud/xEmploymentStatus/54ce3fe48ac9ebbf1869d52d43f715ef",
            "Id": "54ce3fe48ac9ebbf1869d52d43f715ef",
            "xRecordStatus": "Active",
            "xType": "Terminated"
        },
        "xEmploymentTypeLookup": null,
        "xEthnicity": null,
        "xFirstName": "Amanda",
        "xFullName": "Amanda Jones",
        "xGender": null,
        "xLastName": "Jones",
        "xLocationLookup": {
            "__ObjectName": "xLocation",
            "__Self": "https://corehr-api.hrcloud.com/v1/cloud/xLocation/16ed967dfe4607143cde66d04612c22a",
            "Id": "16ed967dfe4607143cde66d04612c22a",
            "xAddress": null,
            "xDescription": null,
            "xLocationCode": "Los Angeles0f53a647-075b-4ea8-b5ea-43e03555a5c0",
            "xLocationName": "Los Angeles",
            "xRecordStatus": "Active"
        },
        "xManagerLookup": null,
        "xMiddleName": null,
        "xNickname": null,
        "xNumberOfPoints": null,
        "xOnboardingFinishedOn": null,
        "xPayFrequencyType": null,
        "xPayRateLookup": null,
        "xPersonalEmail": "amanda51@hotmail.com",
        "xPictures": {
            "OriginalPictureResourceCropParameters": null,
            "SmallResourceId": null,
            "OriginalResourceId": null,
            "MediumResourceId": null
        },
        "xPositionLookup": {
            "__ObjectName": "xPosition",
            "__Self": "https://corehr-api.hrcloud.com/v1/cloud/xPosition/8f72612cca4b41d4981d8dea2374f11f",
            "Id": "8f72612cca4b41d4981d8dea2374f11f",
            "xDescription": null,
            "xPositionCode": "c7b3a128-5af3-47cf-9960-0243b79e5b71",
            "xPositionTitle": "Web Designer",
            "xRecordStatus": "Active"
        },
        "xRecordStatus": "Active",
        "xSalary": {
            "Amount": null,
            "Currency": null
        },
        "xSeparationDate": null,
        "xSeparationReason": null,
        "xStartDate": "2017-01-04T00:00:00Z",
        "xState": "OR",
        "xUpdatedOn": "2019-12-05T07:55:50.067Z",
        "xVeteranStatus": null,
        "xWorkExperienceInCompany": null,
        "xWorkExperiencePrior": {
            "Year": null,
            "Month": null,
            "Day": null
        },
        "xWorkExperienceTotal": null,
        "xWorkPhone": null,
        "xZipCode": "97165"
    }
]

Create a new employee using mapping parameters

POST /xEmployee?{mappingParams}

Create an employee with mapping params. For example, if you wish to map the xLocationLookup and xPositionLookup to the xLocationCode and xPositionCode, xDepartmentLookup to xDepartmentName, xEmploymentStatusLookup to xType and xManagerLookup to xEmail consider the following:

Request URL:

POST https://corehr-api.hrcloud.com/v1/cloud/xEmployee?mapping=xLocationLookup to xLocationCode,xPositionLookup to xPositionCode,xDepartmentLookup to xDepartmentName,xEmploymentStatusLookup to xType,xManagerLookup to xEmail

Request Body:

{
    "xAddress1": "1498 Mill St.",
    "xCity": "Salem",
    "xEmail": "amanda1@mytown.com",
    "xFirstName": "Amanda",
    "xFullName": "Amanda Jones",
    "xLastName": "Jones",
    "xPersonalEmail": "amanda5112@hotmail.com",
    "xRecordStatus": "Active",
    "xStartDate": "2019-01-04T00:00:00Z",
    "xState": "OR",
    "xZipCode": "97165",
    "xEmployeeNumber": "71516411",
    "xEmploymentStatusLookup": {"xType": "Terminated"},
    "xManagerLookup": {"xEmail": "root@phone.com"},
    "xLocationLookup": {"xLocationCode": "LA1"},
    "xPositionLookup": {"xPositionCode": "c7b3a128-5af3-47cf-9960-0243b79e5b71"},
    "xDepartmentLookup": {"xDepartmentName": "Development"}
}

Response:

Status: 200 OK

Response Body:

[
    {
        "Id": "4e6f06d23efa2fb799d7eefe5e03e665",
        "xAddress1": "1498 Mill St.",
        "xAddress2": null,
        "xBonus": {
            "Amount": null,
            "Currency": null
        },
        "xCellPhone": null,
        "xCity": "Salem",
        "xCountry": null,
        "xCreatedOn": "2019-12-05T08:06:50.817Z",
        "xDateOfBirth": null,
        "xDepartmentLookup": {
            "__ObjectName": "xDepartment",
            "__Self": "https://corehr-api.hrcloud.com/v1/cloud/xDepartment/a3a7aa7f8cfc7a46b78ce822d8da642a",
            "Id": "a3a7aa7f8cfc7a46b78ce822d8da642a",
            "xDepartmentCode": "6cdcd962-ca3a-4707-afe1-6fb80def416d",
            "xDepartmentName": "Development",
            "xRecordStatus": "Active"
        },
        "xDivisionLookup": null,
        "xEducationLevel": null,
        "xEmail": "amanda1@mytown.com",
        "xEmployeeNumber": "71516411",
        "xEmploymentStatusLookup": {
            "__ObjectName": "xEmploymentStatus",
            "__Self": "https://corehr-api.hrcloud.com/v1/cloud/xEmploymentStatus/54ce3fe48ac9ebbf1869d52d43f715ef",
            "Id": "54ce3fe48ac9ebbf1869d52d43f715ef",
            "xRecordStatus": "Active",
            "xType": "Terminated"
        },
        "xEmploymentTypeLookup": null,
        "xEthnicity": null,
        "xFirstName": "Amanda",
        "xFullName": "Amanda Jones",
        "xGender": null,
        "xLastName": "Jones",
        "xLocationLookup": {
            "__ObjectName": "xLocation",
            "__Self": "https://corehr-api.hrcloud.com/v1/cloud/xLocation/16ed967dfe4607143cde66d04612c22a",
            "Id": "16ed967dfe4607143cde66d04612c22a",
            "xAddress": null,
            "xDescription": null,
            "xLocationCode": "LA1",
            "xLocationName": "Los Angeles",
            "xRecordStatus": "Active"
        },
        "xManagerLookup": null,
        "xMiddleName": null,
        "xNickname": null,
        "xNumberOfPoints": null,
        "xOnboardingFinishedOn": null,
        "xPayFrequencyType": null,
        "xPayRateLookup": null,
        "xPersonalEmail": "amanda5112@hotmail.com",
        "xPictures": {
            "OriginalPictureResourceCropParameters": null,
            "SmallResourceId": null,
            "OriginalResourceId": null,
            "MediumResourceId": null
        },
        "xPositionLookup": {
            "__ObjectName": "xPosition",
            "__Self": "https://corehr-api.hrcloud.com/v1/cloud/xPosition/8f72612cca4b41d4981d8dea2374f11f",
            "Id": "8f72612cca4b41d4981d8dea2374f11f",
            "xDescription": null,
            "xPositionCode": "c7b3a128-5af3-47cf-9960-0243b79e5b71",
            "xPositionTitle": "Web Designer",
            "xRecordStatus": "Active"
        },
        "xRecordStatus": "Active",
        "xSalary": {
            "Amount": null,
            "Currency": null
        },
        "xSeparationDate": null,
        "xSeparationReason": null,
        "xStartDate": "2019-01-04T00:00:00Z",
        "xState": "OR",
        "xUpdatedOn": "2019-12-05T08:06:53.44Z",
        "xVeteranStatus": null,
        "xWorkExperienceInCompany": null,
        "xWorkExperiencePrior": {
            "Year": null,
            "Month": null,
            "Day": null
        },
        "xWorkExperienceTotal": null,
        "xWorkPhone": null,
        "xZipCode": "97165"
    }
]

Upload an employee picture

POST /xEmployee/Resource/Picture

Uploads a profile picture for the employee. The APIs explained above create an employee record without a picture. To add a picture to the existing record, use this API.

Add the picture file in the Request Body. Request body content type must be multipart/form-data. The response will contain three field for the uploaded resource. For example,

Request:

 POST https://corehr-api.hrcloud.com/v1/cloud/xEmployee/Resource/Picture

Input Parameters:

Attach an appropriate file.

Response:

{
      "smallResourceId": "7a8319932238f45bd0a546eeab3aa5e2",
      "mediumResourceId": "7a8319932238f45bb355dacb1e108741",
      "originalResourceId": "7a8319932238f45b08a1576168546b44"
}

Now update the employee record with this picture resource.

PUT /xEmployee/Picture

For example, Request:

PUT https://corehr-api.hrcloud.com/v1/cloud/xEmployee/Picture

Input parameters:

{
 "Id":"4e6f06d23efa2fb799d7eefe5e03e665",
"smallResourceId": "7a8319932238f45bd0a546eeab3aa5e2",
"mediumResourceId": "7a8319932238f45bb355dacb1e108741",
"originalResourceId": "7a8319932238f45b08a1576168546b44"
}

Create an attachment for an employee

POST /xEmployee/:employeeId/attachments

This API is used to create a new attachment related to an employee.

For example,

Request

POST https://corehr-api.hrcloud.com/v1/cloud/xEmployee/42207b4aefd32d9c9219453bdf988623/attachments

Request Body: The content type must be set to multipart/form-data. Attach a file to be uploaded as an attachment.