Department
Manage departments
List departments
Returns the list of all departments.
Request Information
GEThttps://api-test.hrpeak.com/v2/departments
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/departments
     -H "Authorization: API_KEY"
URI parameters
pageoptional
The zero-based page number. Data type is integer. Default value is 0.
per_pageoptional
The number of items per page. Maximum value is 1000. Data type is integer. Default value is 100.
active_items_onlyoptional
List only items with active status. Data type is boolean. Default value is true.
Request Uri Sample
https://api-test.hrpeak.com/v2/departments/?page=0&per_page=20
Response Information
id
Unique id of the department.
name
Name of the department.
parent
Parent department
id
Unique id of the parent department.
name
Name of the department.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the parent department to an external record.
location
Title of the department.
id
Unique id of the location.
name
Name of the location.
passive
This property value is set to true if the location is not active. Data type is boolean.
external_id
A unique string to associate the location to an external record.
childs
Child departments This property value is an array.
id
Unique id of the child department.
name
Name of the department.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the child department to an external record.
positions
Positions within the department. This property value is an array.
id
Unique id of the position.
name
Name of the position.
passive
This property value is set to true if the position is not active. Data type is boolean.
external_id
A unique string to associate the position to an external record.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the department to an external record.
Sample Response
{
  "status": 0,
  "total_data_count": 1000,
  "data": [
    {
      "id": "4uubeltcdbynyqbhhasccz4mkz",
      "name": "Recruiting Team",
      "parent": {
        "id": "3rgnskxaj3kmypn9u9eynm48rw",
        "name": "Human Resources",
        "external_id": "HR"
      },
      "location": {
        "id": "v4ewjae3fbbnw8zdufz3487xuw",
        "name": "New York City",
        "external_id": "NYC"
      },
      "childs": [
        {
          "id": "4s5c3jeeqflqyccumt8p286npw",
          "name": "Internal Recruitment",
          "external_id": "IRT"
        }
      ],
      "positions": [
        {
          "id": "hgjmb9zz86dxwecvcl6grzdmxz",
          "name": "HR Manager",
          "external_id": "HRMNG"
        }
      ],
      "passive": true,
      "external_id": "RT"
    }
  ]
}
Error Responses
Error messages can vary. More specific error information may be included.
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Get department
Returns the details of a department.
Request Information
GEThttps://api-test.hrpeak.com/v2/departments/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/departments/{id}
     -H "Authorization: API_KEY"
URI parameters
idrequired
Unique id of the department.
Request Uri Sample
https://api-test.hrpeak.com/v2/departments/75hfns9qh6d7ymnrxhuph2lx3w
Response Information
id
Unique id of the department.
name
Name of the department.
parent
Parent department
id
Unique id of the parent department.
name
Name of the department.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the parent department to an external record.
location
Title of the department.
id
Unique id of the location.
name
Name of the location.
passive
This property value is set to true if the location is not active. Data type is boolean.
external_id
A unique string to associate the location to an external record.
childs
Child departments This property value is an array.
id
Unique id of the child department.
name
Name of the department.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the child department to an external record.
positions
Positions within the department. This property value is an array.
id
Unique id of the position.
name
Name of the position.
passive
This property value is set to true if the position is not active. Data type is boolean.
external_id
A unique string to associate the position to an external record.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the department to an external record.
Sample Response
{
  "status": 0,
  "data": {
    "id": "s6swenzx3g9mwrmx4mb9ryxz3q",
    "name": "Recruiting Team",
    "parent": {
      "id": "2v4yeme2tyqlwjx7aqrfeqg2nq",
      "name": "Human Resources",
      "external_id": "HR"
    },
    "location": {
      "id": "k6ek2ncb2utxykmb5mdyc5qufq",
      "name": "New York City",
      "external_id": "NYC"
    },
    "childs": [
      {
        "id": "d4pu8r5utwsuwcl2apcjc69ph3",
        "name": "Internal Recruitment",
        "external_id": "IRT"
      }
    ],
    "positions": [
      {
        "id": "9mgj9r89jbfkyfnqn9et5bc7x2",
        "name": "HR Manager",
        "external_id": "HRMNG"
      }
    ],
    "passive": true,
    "external_id": "RT"
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Get department by external id
Returns the details of a department.
Request Information
GEThttps://api-test.hrpeak.com/v2/departments/external_id/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/departments/external_id/{id}
     -H "Authorization: API_KEY"
URI parameters
idrequired
A unique string to associate the department to an external record.
Request Uri Sample
https://api-test.hrpeak.com/v2/departments/external_id/RT
Response Information
id
Unique id of the department.
name
Name of the department.
parent
Parent department
id
Unique id of the parent department.
name
Name of the department.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the parent department to an external record.
location
Title of the department.
id
Unique id of the location.
name
Name of the location.
passive
This property value is set to true if the location is not active. Data type is boolean.
external_id
A unique string to associate the location to an external record.
childs
Child departments This property value is an array.
id
Unique id of the child department.
name
Name of the department.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the child department to an external record.
positions
Positions within the department. This property value is an array.
id
Unique id of the position.
name
Name of the position.
passive
This property value is set to true if the position is not active. Data type is boolean.
external_id
A unique string to associate the position to an external record.
passive
This property value is set to true if the department is not active. Data type is boolean.
external_id
A unique string to associate the department to an external record.
Sample Response
{
  "status": 0,
  "data": {
    "id": "t7358mjqvf7fwql27sdgeqxmgw",
    "name": "Recruiting Team",
    "parent": {
      "id": "b8qrecnl59payjmyjegj3ewqzw",
      "name": "Human Resources",
      "external_id": "HR"
    },
    "location": {
      "id": "zfnpj69j8r9lwxns5b2afsnhl3",
      "name": "New York City",
      "external_id": "NYC"
    },
    "childs": [
      {
        "id": "y8x8jvpvazggwqc6yly3drcmfw",
        "name": "Internal Recruitment",
        "external_id": "IRT"
      }
    ],
    "positions": [
      {
        "id": "243zasgnyew9yqbcn3dhdxfvya",
        "name": "HR Manager",
        "external_id": "HRMNG"
      }
    ],
    "passive": true,
    "external_id": "RT"
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Insert department
Create a new department.
Request Information
POSThttps://api-test.hrpeak.com/v2/departments
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl -X POST https://api-test.hrpeak.com/v2/departments
     -H "Authorization: API_KEY"
     -d {JSON body}
JSON body object
namerequired
Name of the department. Max length is 255.
external_idoptional
A unique string to associate the department to an external record. Max length is 50.
parent_idoptional
Unique id of the parent department. Max length is 36.
parent_external_idoptional
A unique string to associate the parent department to an external record. Max length is 50.
location_idoptional
Unique id of the location. Max length is 36.
location_external_idoptional
A unique string to associate the location to an external record. Max length is 50.
Request Body Sample
{
  "name": "Recruiting Team"
}
{
  "name": "Recruiting Team",
  "external_id": "RT",
  "parent_id": "c959cqm9rgchwtzvfemruuy8yq",
  "location_external_id": "NYC"
}
Response Information
Unique id of the department.
Sample Response
{
  "status": 0,
  "data": "pv95r5r8nte8yemz8jbaps9y92"
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Name already exist
{
  "status": 1,
  "error_message": "Another item with the same name already exists."
}
External id already exist
{
  "status": 2,
  "error_message": "Another item with the same external id already exists."
}
Parent not found
{
  "status": 3,
  "error_message": "Parent item is not found."
}
Location not found
{
  "status": 4,
  "error_message": "Location item is not found. Add the location first or submit an existing location."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Update department
Update a department.
Request Information
PATCHhttps://api-test.hrpeak.com/v2/departments/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl -X PATCH https://api-test.hrpeak.com/v2/departments/{id}
     -H "Authorization: API_KEY"
     -d {JSON body}
Below is the list of properties that can be updated on the item. Only the properties on the JSON data are updated. Don't include properties that you don't want updated in JSON.
URI parameters
idrequired
Unique id of the department.
JSON body object
nameoptional
Name of the department. Max length is 255.
external_idoptional
A unique string to associate the department to an external record. Max length is 50.
activeoptional
This property value is set to true if the department is not active. Data type is boolean.
parent_idoptional
Unique id of the parent department. Max length is 36.
parent_external_idoptional
A unique string to associate the parent department to an external record. Max length is 50.
location_idoptional
Unique id of the location. Max length is 36.
location_external_idoptional
A unique string to associate the location to an external record. Max length is 50.
Request Uri Sample
https://api-test.hrpeak.com/v2/departments/hnytzfgdsuvjyac6b9upj88cxw
Request Body Sample
Update only name value.
{
  "name": "Recruiting Team"
}
Update name and status.
{
  "name": "Recruiting Team",
  "active": false
}
Response Information
id
Unique id of the department.
name
Name of the department.
passive
This property value is set to true if the department is not active. Data type is boolean.
parent_id
Unique id of the parent department.
location_id
Unique id of the location.
Sample Response
{
  "status": 0,
  "data": {
    "id": "tryrjrsk4f8myjxtbwurq3jg2x",
    "name": "Recruiting Team",
    "passive": true,
    "parent_id": "75hl9993brejy7cezfz73bafsz",
    "location_id": "5es4dn3dhslgyply3wnj2q62xx"
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Name already exist
{
  "status": 1,
  "error_message": "Another item with the same name already exists."
}
External id already exist
{
  "status": 2,
  "error_message": "Another item with the same external id already exists."
}
Parent not found
{
  "status": 3,
  "error_message": "Parent item is not found."
}
Location not found
{
  "status": 4,
  "error_message": "Location item is not found. Add the location first or submit an existing location."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Update department by external id
Update a department.
Request Information
PATCHhttps://api-test.hrpeak.com/v2/departments/external_id/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl -X PATCH https://api-test.hrpeak.com/v2/departments/external_id/{id}
     -H "Authorization: API_KEY"
     -d {JSON body}
Below is the list of properties that can be updated on the item. Only the properties on the JSON data are updated. Don't include properties that you don't want updated in JSON.
URI parameters
idrequired
A unique string to associate the department to an external record.
JSON body object
nameoptional
Name of the department. Max length is 255.
external_idoptional
A unique string to associate the department to an external record. Max length is 50.
activeoptional
This property value is set to true if the department is not active. Data type is boolean.
parent_idoptional
Unique id of the parent department. Max length is 36.
parent_external_idoptional
A unique string to associate the parent department to an external record. Max length is 50.
location_idoptional
Unique id of the location. Max length is 36.
location_external_idoptional
A unique string to associate the location to an external record. Max length is 50.
Request Uri Sample
https://api-test.hrpeak.com/v2/departments/external_id/RT
Request Body Sample
Update only name value.
{
  "name": "Recruiting Team"
}
Update name and status.
{
  "name": "Recruiting Team",
  "active": false
}
Response Information
id
Unique id of the department.
name
Name of the department.
passive
This property value is set to true if the department is not active. Data type is boolean.
parent_id
Unique id of the parent department.
location_id
Unique id of the location.
Sample Response
{
  "status": 0,
  "data": {
    "id": "ndhmty36mru8wcvs277np99y6a",
    "name": "Recruiting Team",
    "passive": true,
    "parent_id": "cfkwm7empy48ywv9fkzjpnuxc3",
    "location_id": "xt8bapafqdz7wpzb4683paylq3"
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Name already exist
{
  "status": 1,
  "error_message": "Another item with the same name already exists."
}
External id already exist
{
  "status": 2,
  "error_message": "Another item with the same external id already exists."
}
Parent not found
{
  "status": 3,
  "error_message": "Parent item is not found."
}
Location not found
{
  "status": 4,
  "error_message": "Location item is not found. Add the location first or submit an existing location."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Delete department
Delete a department.
Request Information
DELETEhttps://api-test.hrpeak.com/v2/departments/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl -X DELETE https://api-test.hrpeak.com/v2/departments/{id}
     -H "Authorization: API_KEY"
URI parameters
idrequired
Unique id of the department.
Request Uri Sample
https://api-test.hrpeak.com/v2/departments/97qx4lc8l4wfwdcm92dmh9m8yx
Response Information
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Delete department by external id
Delete a department.
Request Information
DELETEhttps://api-test.hrpeak.com/v2/departments/external_id/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl -X DELETE https://api-test.hrpeak.com/v2/departments/external_id/{id}
     -H "Authorization: API_KEY"
URI parameters
idrequired
A unique string to associate the department to an external record.
Request Uri Sample
https://api-test.hrpeak.com/v2/departments/external_id/RT
Response Information
Error Responses
Error messages can vary. More specific error information may be included.
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Import
Upload all your department data at once. New records are added, existing records are updated, and old records not included in the uploaded data are deleted or deactivated.

The data loading process operates asynchronously. The loaded data is added to the data loading queue. If a data loading process has already been initiated, the previous loading process is canceled. You can check whether the data loading process is complete within the application.
Request Information
POSThttps://api-test.hrpeak.com/v2/departments/import
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl -X POST https://api-test.hrpeak.com/v2/departments/import
     -H "Authorization: API_KEY"
     -d {JSON body}
URI parameters
delete_not_existing_recordsoptional
Delete old records that are not in the loaded data? Data type is boolean. Default value is false.
auto_startoptional
Should the data update process begin immediately after loading? If the parameter value is sent as 'false', the validity of the sent data is checked and only the number of records to be added, updated and deleted is returned and no data update is performed. Data type is boolean. Default value is true.
JSON body object
datarequired
This property value is an array.
idrequired
A unique string to associate the department to an external record. Max length is 50.
namerequired
Name of the department. Max length is 255.
parent_idoptional
A unique string to associate the parent department to an external record. Max length is 50.
location_idoptional
A unique string to associate the location to an external record. Max length is 50.
Request Uri Sample
https://api-test.hrpeak.com/v2/departments/import/?delete_not_existing_records=true&auto_start=false
Request Body Sample
The body must contain all department data you want to load. Load all departments in a single JSON array.
[
  {
    "id": "IRT",
    "name": "Internal Recruitment",
    "parent_id": "RT",
    "location_id": "NYC"
  },
  {
    "id": "RT",
    "name": "Recruiting Team",
    "parent_id": "HR"
  },
  {
    "id": "HR",
    "name": "Human Resources",
    "location_id": "SF"
  }
]
Response Information
insert
Number of departments to add. Data type is integer.
update
Number of departments to update. Data type is integer.
delete
Number of departments to delete. Data type is integer.
Sample Response
4 records will be added, 10 records will be updated, 1 record will be deleted.
{
  "status": 0,
  "data": {
    "insert": 4,
    "update": 10,
    "delete": 1
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Data upload invalid data
{
  "status": 1,
  "error_message": "Invalid data. Invalid records can be obtained from the data parameter.",
  "data": [
    "Error 1",
    "Error 2",
    ". . ."
  ]
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}