API Documentation

Title

Manage titles

List titles

Returns the list of all titles.

Request Information

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

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

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

Response Information

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.

Sample Response

{
  "status": 0,
  "total_data_count": 1000,
  "data": [
    {
      "id": "x7b6nlsauwn7yvnpfxq6c48lgs",
      "name": "Manager",
      "passive": true,
      "external_id": "T001"
    }
  ]
}

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 title

Returns the details of a title.

Request Information

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

URI parameters

idrequired

Unique id of the title.

Request Uri Sample

https://api-test.hrpeak.com/v2/titles/2vrauvcapxu3w7c7ytnulj2abq

Response Information

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "css24sjrxucsy6cx292p44e76q",
    "name": "Manager",
    "passive": true,
    "external_id": "T001"
  }
}

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

Returns the details of a title.

Request Information

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

URI parameters

idrequired

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

Request Uri Sample

https://api-test.hrpeak.com/v2/titles/external_id/T001

Response Information

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "kmdrf2cvq2egwgl2ta3yw3behx",
    "name": "Manager",
    "passive": true,
    "external_id": "T001"
  }
}

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 title

Create a new title.

Request Information

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

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

JSON body object

namerequired

Name of the title. Max length is 255.

external_idoptional

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

Request Body Sample

{
  "name": "Manager"
}

{
  "name": "Manager",
  "external_id": "T001"
}

Response Information

Unique id of the title.

Sample Response

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

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

Internal server error

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

Update title

Update a title.

Request Information

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

JSON body object

nameoptional

Name of the title. Max length is 255.

external_idoptional

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

activeoptional

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

Request Uri Sample

https://api-test.hrpeak.com/v2/titles/8etld59ycxnpwtb8l6e3x7urja

Request Body Sample

Update only name value.

{
  "name": "Manager"
}

Update name and status.

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

Response Information

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "bg649jysw48zy2lvetg2cswawa",
    "name": "Manager",
    "passive": true
  }
}

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

Internal server error

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

Update title by external id

Update a title.

Request Information

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

JSON body object

nameoptional

Name of the title. Max length is 255.

external_idoptional

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

activeoptional

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

Request Uri Sample

https://api-test.hrpeak.com/v2/titles/external_id/T001

Request Body Sample

Update only name value.

{
  "name": "Manager"
}

Update name and status.

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

Response Information

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "94n22pdtsezvwbbklse38sbwes",
    "name": "Manager",
    "passive": true
  }
}

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

Internal server error

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

Delete title

Delete a title.

Request Information

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

URI parameters

idrequired

Unique id of the title.

Request Uri Sample

https://api-test.hrpeak.com/v2/titles/rd5gndcur8a2wgnppv4rgvueas

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

Delete a title.

Request Information

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

URI parameters

idrequired

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

Request Uri Sample

https://api-test.hrpeak.com/v2/titles/external_id/T001

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 title 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/titles/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/titles/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 location to an external record. Max length is 50.

namerequired

Name of the location. Max length is 255.

Request Uri Sample

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

Request Body Sample

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

[
  {
    "id": "T001",
    "name": "Manager"
  },
  {
    "id": "T002",
    "name": "Director"
  },
  {
    "id": "T003",
    "name": "Team Lead"
  }
]

Response Information

insert

Number of titles to add. Data type is integer.

update

Number of titles to update. Data type is integer.

delete

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