API Documentation

Position

Manage positions

List positions

Returns the list of all positions.

Request Information

GEThttps://api-test.hrpeak.com/v2/positions

The API uses basic authentication and the API key must be sent in the Authorization request header.

curl https://api-test.hrpeak.com/v2/positions
-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/positions/?page=0&per_page=20

Response Information

Unique id of the position.

name

Name of the position.

parent

Parent position

Unique id of the parent 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 parent position to an external record.

title

Title of the position.

Unique id of the title.

name

Name of the title.

passive

This property value is set to true if the title is not active. Data type is boolean.

external_id

A unique string to associate the title to an external record.

childs

Child positions This property value is an array.

Unique id of the child 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 child position to an external record.

departments

Departments containing the position This property value is an array.

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.

external_id

A unique string to associate the department to an external record.

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.

Sample Response

{
  "status": 0,
  "total_data_count": 1000,
  "data": [
    {
      "id": "sg6pt2w6ue9rwrl2lzu5rbvjvw",
      "name": "HR Manager",
      "parent": {
        "id": "99znk5v6bp6by8mdxmampv4xk2",
        "name": "General Manager",
        "external_id": "GM"
      },
      "title": {
        "id": "4efhszt8y9eeyxnfb5qq96g2wa",
        "name": "Manager",
        "external_id": "T001"
      },
      "childs": [
        {
          "id": "k6y3qee2wg2my2lcdt44qt9kkz",
          "name": "IT Recruiter",
          "external_id": "ITR"
        }
      ],
      "departments": [
        {
          "id": "2xt8eahzz96symvt24bpzhf7ps",
          "name": "Recruiting Team",
          "external_id": "RT"
        }
      ],
      "passive": true,
      "external_id": "HRMNG"
    }
  ]
}

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 position

Returns the details of a position.

Request Information

GEThttps://api-test.hrpeak.com/v2/positions/{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/positions/{id}
-H "Authorization: API_KEY"

URI parameters

idrequired

Unique id of the position.

Request Uri Sample

https://api-test.hrpeak.com/v2/positions/tjm6n52uxrxuwdzy78rvppms3x

Response Information

Unique id of the position.

name

Name of the position.

parent

Parent position

Unique id of the parent 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 parent position to an external record.

title

Title of the position.

Unique id of the title.

name

Name of the title.

passive

This property value is set to true if the title is not active. Data type is boolean.

external_id

A unique string to associate the title to an external record.

childs

Child positions This property value is an array.

Unique id of the child 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 child position to an external record.

departments

Departments containing the position This property value is an array.

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.

external_id

A unique string to associate the department to an external record.

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "d3bja553cjqywmzqntqby6gyhw",
    "name": "HR Manager",
    "parent": {
      "id": "u322fpsnzgzny2luybyew3dft2",
      "name": "General Manager",
      "external_id": "GM"
    },
    "title": {
      "id": "g6qvmc6gcllywgzljld7m3s9tq",
      "name": "Manager",
      "external_id": "T001"
    },
    "childs": [
      {
        "id": "rv8f6qadgcwywfvjw9dgke3r2x",
        "name": "IT Recruiter",
        "external_id": "ITR"
      }
    ],
    "departments": [
      {
        "id": "4tk2uzngmvrnwevyt5hs2tycjz",
        "name": "Recruiting Team",
        "external_id": "RT"
      }
    ],
    "passive": true,
    "external_id": "HRMNG"
  }
}

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 position by external id

Returns the details of a position.

Request Information

GEThttps://api-test.hrpeak.com/v2/positions/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/positions/external_id/{id}
-H "Authorization: API_KEY"

URI parameters

idrequired

A unique string to associate the position to an external record.

Request Uri Sample

https://api-test.hrpeak.com/v2/positions/external_id/HRMNG

Response Information

Unique id of the position.

name

Name of the position.

parent

Parent position

Unique id of the parent 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 parent position to an external record.

title

Title of the position.

Unique id of the title.

name

Name of the title.

passive

This property value is set to true if the title is not active. Data type is boolean.

external_id

A unique string to associate the title to an external record.

childs

Child positions This property value is an array.

Unique id of the child 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 child position to an external record.

departments

Departments containing the position This property value is an array.

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.

external_id

A unique string to associate the department to an external record.

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "axnk8zj8m86cyknlxewnj3jqbz",
    "name": "HR Manager",
    "parent": {
      "id": "dh6mnsra6kahw4bu62egrsmq63",
      "name": "General Manager",
      "external_id": "GM"
    },
    "title": {
      "id": "elxmwf2sgyr8wtm2ytagyc3tz2",
      "name": "Manager",
      "external_id": "T001"
    },
    "childs": [
      {
        "id": "9mqytzz8dbb4yknnwykquhb5d2",
        "name": "IT Recruiter",
        "external_id": "ITR"
      }
    ],
    "departments": [
      {
        "id": "efdbbw99qshfyzllp4qsgraedq",
        "name": "Recruiting Team",
        "external_id": "RT"
      }
    ],
    "passive": true,
    "external_id": "HRMNG"
  }
}

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 position

Create a new position.

Request Information

POSThttps://api-test.hrpeak.com/v2/positions

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/positions
-H "Authorization: API_KEY"
-d {JSON body}

JSON body object

namerequired

Name of the position. Max length is 255.

external_idoptional

A unique string to associate the position to an external record. Max length is 50.

parent_idoptional

Unique id of the parent position. Max length is 36.

parent_external_idoptional

A unique string to associate the parent position to an external record. Max length is 50.

title_idoptional

Unique id of the title. Max length is 36.

title_external_idoptional

A unique string to associate the title to an external record. Max length is 50.

department_idoptional

Unique id of the department. Max length is 36.

department_external_idoptional

A unique string to associate the department to an external record. Max length is 50.

Request Body Sample

{
  "name": "HR Manager"
}

{
  "name": "HR Manager",
  "external_id": "HRMNG",
  "parent_id": "nzkn92bxrhtvycltezlfwrgjua",
  "title_external_id": "T001",
  "department_external_id": "RT"
}

Response Information

Unique id of the position.

Sample Response

{
  "status": 0,
  "data": "gx4danakqvlawdnlwqjccn9ega"
}

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."
}

Title not found

{
  "status": 4,
  "error_message": "Title item is not found. Add the title first or submit  an existing title."
}

Organization not found

{
  "status": 5,
  "error_message": "Department item is not found. Add the department first or submit an existing department."
}

Internal server error

{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}

Update position

Update a position.

Request Information

PATCHhttps://api-test.hrpeak.com/v2/positions/{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/positions/{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 position.

JSON body object

nameoptional

Name of the position. Max length is 255.

external_idoptional

A unique string to associate the position to an external record. Max length is 50.

activeoptional

This property value is set to true if the position is not active. Data type is boolean.

parent_idoptional

Unique id of the parent position. Max length is 36.

parent_external_idoptional

A unique string to associate the parent position to an external record. Max length is 50.

title_idoptional

Unique id of the title. Max length is 36.

title_external_idoptional

A unique string to associate the title to an external record. Max length is 50.

Request Uri Sample

https://api-test.hrpeak.com/v2/positions/33pwqgde9utry3nbndqkss8dtq

Request Body Sample

Update only name value.

{
  "name": "HR Manager"
}

Update name and status.

{
  "name": "HR Manager",
  "active": false
}

Response Information

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.

parent_id

Unique id of the parent position.

title_id

Unique id of the title.

Sample Response

{
  "status": 0,
  "data": {
    "id": "5cayd5kkux5dypzdt8qmqfplf2",
    "name": "HR Manager",
    "passive": true,
    "parent_id": "jy6rvpuj56xsw8l4h3hfkltjc3",
    "title_id": "2h89db83cjtqyezyl3xy8rk5rz"
  }
}

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."
}

Title not found

{
  "status": 4,
  "error_message": "Title item is not found. Add the title first or submit  an existing title."
}

Organization not found

{
  "status": 5,
  "error_message": "Department item is not found. Add the department first or submit an existing department."
}

Internal server error

{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}

Update position by external id

Update a position.

Request Information

PATCHhttps://api-test.hrpeak.com/v2/positions/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/positions/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 position to an external record.

JSON body object

nameoptional

Name of the position. Max length is 255.

external_idoptional

A unique string to associate the position to an external record. Max length is 50.

activeoptional

This property value is set to true if the position is not active. Data type is boolean.

parent_idoptional

Unique id of the parent position. Max length is 36.

parent_external_idoptional

A unique string to associate the parent position to an external record. Max length is 50.

title_idoptional

Unique id of the title. Max length is 36.

title_external_idoptional

A unique string to associate the title to an external record. Max length is 50.

Request Uri Sample

https://api-test.hrpeak.com/v2/positions/external_id/HRMNG

Request Body Sample

Update only name value.

{
  "name": "HR Manager"
}

Update name and status.

{
  "name": "HR Manager",
  "active": false
}

Response Information

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.

parent_id

Unique id of the parent position.

title_id

Unique id of the title.

Sample Response

{
  "status": 0,
  "data": {
    "id": "9fnl6gnh5k8xyyxqrp8jw8mm93",
    "name": "HR Manager",
    "passive": true,
    "parent_id": "pz38valf3urhyrmgw6sg9zzu4w",
    "title_id": "qaflqnwu9n46wpzl3rs4ccdehs"
  }
}

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."
}

Title not found

{
  "status": 4,
  "error_message": "Title item is not found. Add the title first or submit  an existing title."
}

Organization not found

{
  "status": 5,
  "error_message": "Department item is not found. Add the department first or submit an existing department."
}

Internal server error

{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}

Delete position

Delete a position.

Request Information

DELETEhttps://api-test.hrpeak.com/v2/positions/{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/positions/{id}
-H "Authorization: API_KEY"

URI parameters

idrequired

Unique id of the position.

Request Uri Sample

https://api-test.hrpeak.com/v2/positions/gc6mvlrajt78ybzjrqmrnpfc3x

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 position by external id

Delete a position.

Request Information

DELETEhttps://api-test.hrpeak.com/v2/positions/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/positions/external_id/{id}
-H "Authorization: API_KEY"

URI parameters

idrequired

A unique string to associate the position to an external record.

Request Uri Sample

https://api-test.hrpeak.com/v2/positions/external_id/HRMNG

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 position 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/positions/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/positions/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 position to an external record. Max length is 50.

namerequired

Name of the position. Max length is 255.

parent_idoptional

A unique string to associate the parent position to an external record. Max length is 50.

title_idoptional

A unique string to associate the title to an external record. Max length is 50.

department_idoptional

A unique string to associate the department to an external record. Max length is 50.

Request Uri Sample

https://api-test.hrpeak.com/v2/positions/import/?delete_not_existing_records=true&auto_start=false

Request Body Sample

The body must contain all position data you want to load. Load all positions in a single JSON array.

[
  {
    "id": "ITR",
    "name": "IT Recruiter",
    "parent_id": "HRMNG",
    "title_id": "T001",
    "department_id": "RT"
  },
  {
    "id": "HRMNG",
    "name": "HR Manager",
    "parent_id": "GM"
  },
  {
    "id": "GM",
    "name": "General Manager",
    "title_id": "T002",
    "department_id": "HR"
  }
]

Response Information

insert

Number of positions to add. Data type is integer.

update

Number of positions to update. Data type is integer.

delete

Number of positions 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."
}