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.