(Quick Reference) Service: Upsert an employee

Description: This web service is used to insert an employee object to the database if it does not already exist, or update it.

URL with external_id:


Method: POST

Request content type: application/x-www-form-urlencoded or multipart/form-data


NameDescriptionTypeRequiredExample values
reference Stringyes 
firstName Stringyes 
lastName Stringyes 
employeeGroupIdThe ID of the employee group.Stringno 
managerIdThe ID of employee.Stringno 
enabledBy default, it is set to trueBooleannotrue, false
mobile Stringno 
imageFileImage of employee can be in jpg, gif, png or bmp formatmultipartno 

Success Output

Success case: response.status=201

  "id": 22,
  "reference": "emp_22",
  "firstName": "Jane",
  "lastName": "Doe",
  "mobile": "001-555-555-1212",
  "enabled": true,
  "managerReference": "emp-00",
  "employeeGroupReference": "60837-111",
  "manager": {
    "id": 3,
    "reference": "emp-00",
    "href": "/api/v1.0/employees/3"
  "employeeGroup": {
    "id": 1,
    "reference": "60837-111",
    "name": "Group1",
    "href": "/api/v1.0/employeeGroups/1"
  "avatar": "BASE_URL/entity1-1450169988465/avatar/1471442935596_1448038178_supportfemale.png",
  "organization": "entity1",
  "dateCreated": "2016-08-17T13:45:17Z",
  "lastUpdated": "2016-08-17T14:08:55Z"

To get resized images, add prefix small_ or medium_ to the link url before the image's name, for example:

Failure Output

Failure case:response.status = 400

  "error": "save_failed",
  "error_description": "Failed to save instance."

  "error": "not_unique",
  "error_description": "reference already used"

  "error": "missing_param",
  "error_description": "firstName parameter is missing"
  "error": "unsupported_file_type",
  "error_description": "image format not supported."

  "error": "exceeded_file_size",
  "error_description": "image size should not exceed 2Mo"

Failure case:response.status = 404

  "error": "not_found",
  "error_description": "The manager with the id 22 doesn't exist."

Failure case:response.status = 500
  "error": "server_error",
  "error_description": "Oops! Something went wrong..."