Find Listings
This endpoint finds listings for the provided parameters.
All date fields included in the body parameters need to be specified as ISO8601-formatted date strings.
Date fields should follow a “YYYY-MM-DD” format.
This endpoint only returns vacancies that are active.
You can provide either a group id through the group_id parameter or a group external reference through the group_external_ref attribute to filter the list of retrieved listings down.
Do not provide both, as this will result in the request failing.
You must provide either a group_id or group_external_ref, otherwise the request will fail.
Header
The authentication token for your request.
Body
The id of the group of the listings to retrieve.
The external reference of the group of the listings to retrieve.
The external identifier of the listings to retrieve.
The internal identifier of the listings to retrieve.
The API returns a maximum of 100 records per call.
You can use this parameter to load the next set of records by passing in the value returned in the response, under last_id.
Response
The last id in the set of results returned for this API call.
You can use this value in the after-id parameter to load the next set of results.
If there are no more results to load, this value will be -1.
The listings retrieved by the endpoint.
Errors
Listed below are common errors that may be returned by the endpoint, along with their corresponding status code.
Status Code - 400
{
"error": {
"type": "missing_authorization",
"message": "Your request does not include an 'Authorization' header with a bearer token for your account."
}
}
Status Code - 401
{
"error": {
"type": "expired_token",
"message": "The bearer token you have provided in the 'Authorization' header has expired. Please obtain a new one."
}
}
Status Code - 401
{
"error": {
"type": "invalid_authorization",
"message": "The bearer token you have provided in the 'Authorization' header is invalid."
}
}
Status Code - 400
Returned if both a group id and group_external_ref are provided
{
"error": {
"type": "both_group_identifiers_provided",
"message": "You have provided both a group id and group external reference for the find listings operation. Please only provide one of the two."
}
}
Status Code - 400
Returned if neither a group id nor a group_external_ref are provided
{
"error": {
"type": "no_group_identifier_provided",
"message": "You have not provided either a group id or a group external reference for the find listings operation. Please provide one of the two."
}
}
Status Code - 401
Returned if the user does not have access to the provided group
{
"error": {
"type": "no_access_to_group",
"message": "You do not have access to view information on the group you have provided in the request."
}
}
Status Code - 404
Returned if no listing records can be found matching the provided information.
{
"error": {
"type": "not_found",
"message": "There are no listing records matching the information provided."
}
}