API Documentation

Location

Manage locations

List locations

Returns the list of all locations.

Request Information

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

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

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

Response Information

Unique id of the location.

name

Name of the location.

region

Region of the location.

Unique id of the region.

name

Name of the region.

passive

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

external_id

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

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.

Sample Response

{
  "status": 0,
  "total_data_count": 1000,
  "data": [
    {
      "id": "ehcpn748mep7yrnb5pdrybcaus",
      "name": "New York City",
      "region": {
        "id": "5v96mdzw6naryflbwz3r37xfw3",
        "name": "West",
        "external_id": "W"
      },
      "passive": true,
      "external_id": "NYC"
    }
  ]
}

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 location

Returns the details of a location.

Request Information

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

URI parameters

idrequired

Unique id of the location.

Request Uri Sample

https://api-test.hrpeak.com/v2/locations/xn8m7j5xhy7qyevl4yxygbzpaw

Response Information

Unique id of the location.

name

Name of the location.

region

Region of the location.

Unique id of the region.

name

Name of the region.

passive

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

external_id

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

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "eg4ene5xstwmwwxdzdhsxvlmp2",
    "name": "New York City",
    "region": {
      "id": "n6bmkyy6vxkdyfmtlclsgdl2bw",
      "name": "West",
      "external_id": "W"
    },
    "passive": true,
    "external_id": "NYC"
  }
}

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

Returns the details of a location.

Request Information

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

URI parameters

idrequired

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

Request Uri Sample

https://api-test.hrpeak.com/v2/locations/external_id/NYC

Response Information

Unique id of the location.

name

Name of the location.

region

Region of the location.

Unique id of the region.

name

Name of the region.

passive

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

external_id

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

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "v2n86etnxxtjy8vjenfyc3umhq",
    "name": "New York City",
    "region": {
      "id": "4vmhtlhzylbkwecy5fxtx32fq3",
      "name": "West",
      "external_id": "W"
    },
    "passive": true,
    "external_id": "NYC"
  }
}

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 location

Create a new location.

Request Information

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

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

JSON body object

namerequired

Name of the location. Max length is 255.

external_idoptional

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

region_idoptional

Unique id of the region. Max length is 36.

region_external_idoptional

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

Request Body Sample

{
  "name": "New York City"
}

{
  "name": "New York City",
  "external_id": "NYC",
  "region_id": "ftrsjp23bajdw8xabvyb7xsffq"
}

Response Information

Unique id of the location.

Sample Response

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

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

Region not found

{
  "status": 3,
  "error_message": "Region item is not found. Add the region first or submit an existing region."
}

Internal server error

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

Update location

Update a location.

Request Information

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

JSON body object

nameoptional

Name of the location. Max length is 255.

external_idoptional

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

activeoptional

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

region_idoptional

Unique id of the region. Max length is 36.

region_external_idoptional

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

Request Uri Sample

https://api-test.hrpeak.com/v2/locations/265f5b9fvy5uwuv4fc2wtzbq5s

Request Body Sample

Update only name value.

{
  "name": "New York City"
}

Update name and status.

{
  "name": "New York City",
  "active": false
}

Response Information

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "qf4tyj99my7fw8b3du2aeput9z",
    "name": "New York City",
    "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."
}

Region not found

{
  "status": 3,
  "error_message": "Region item is not found. Add the region first or submit an existing region."
}

Internal server error

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

Update location by external id

Update a location.

Request Information

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

JSON body object

nameoptional

Name of the location. Max length is 255.

external_idoptional

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

activeoptional

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

region_idoptional

Unique id of the region. Max length is 36.

region_external_idoptional

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

Request Uri Sample

https://api-test.hrpeak.com/v2/locations/external_id/NYC

Request Body Sample

Update only name value.

{
  "name": "New York City"
}

Update name and status.

{
  "name": "New York City",
  "active": false
}

Response Information

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.

Sample Response

{
  "status": 0,
  "data": {
    "id": "3mclmk322tb2wdz7tyckkmhmhz",
    "name": "New York City",
    "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."
}

Region not found

{
  "status": 3,
  "error_message": "Region item is not found. Add the region first or submit an existing region."
}

Internal server error

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

Delete location

Delete a location.

Request Information

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

URI parameters

idrequired

Unique id of the location.

Request Uri Sample

https://api-test.hrpeak.com/v2/locations/yuchknyj3ugtysc93r2xugwn53

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

Delete a location.

Request Information

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

URI parameters

idrequired

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

Request Uri Sample

https://api-test.hrpeak.com/v2/locations/external_id/NYC

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 location 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/locations/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/locations/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/locations/import/?delete_not_existing_records=true&auto_start=false

Request Body Sample

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

[
  {
    "id": "NYC",
    "name": "New York City"
  },
  {
    "id": "SF",
    "name": "San Francisco"
  },
  {
    "id": "LA",
    "name": "Los Angeles"
  }
]

Response Information

insert

Number of locations to add. Data type is integer.

update

Number of locations to update. Data type is integer.

delete

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