NAV
javascript

Openings

The Openings API lets you retrieve data related to openings for a client. Some javascript examples on using the API can be found at https://github.com/Recruiterbox/jsapi-client

Attributes

Attribute Description
id string
title string
description string
location.city string
location.state string
location.country string
tags list
hosted_url string
allows_remote boolean
position_type choice(contract, full_time, part_time)
team string

List of all Openings

$.ajax({
  url: 'https://jsapi.recruiterbox.com/v1/openings?client_name=demoaccount',
  contentType: 'application/json',
  success: function(response) {
      console.log(response);
    }
  });

The above snippet logs the JSON response like the example below

{
    "objects": [
      {
        "id": "a42f3",
        "title": "UX - Engineer",
        "description": "UX - Engineer",
        "location": {
          "city": "San Jose",
          "state": "CA",
          "country": "USA"
        },
        "tags": ["Dev","UX"],
        "hosted_url": "https://demoaccount.recruiterbox.com/jobs/ad3e",
        "allows_remote": true,
        "position_type": "contract",
        "team": "FrontEnd Engineers"
      }
    ],
    "meta": {
      "total_count":1,
      "limit": 20,
      "offset": 0
    }
}

This endpoint retrieves all openings.

HTTP Request

GET https://jsapi.recruiterbox.com/v1/openings/

Query Parameters

Parameter Description
client_name The client name eg: recruiterbox (mandatory)
tags Filter by tags
city Filter by city
state Filter by state
country Filter by country
title Filter by title
description Filter by description
order_by Sort by created_on, modified_on attributes. Use “-” to sort in descending order
allows_remote Filter by remote working allowed/ not allowed
position_type Filter by one of the position_type contract, full_time, part_time
team Filter by team

Get a specific Opening

$.ajax({
  url: 'https://jsapi.recruiterbox.com/v1/openings/a42f3?client_name=demoaccount',
  contentType: 'application/json',
  success: function(response) {
      console.log(response);
    }
  });

The above snippet logs the JSON response like the example below

{
  "id": "a42f3",
  "title": "UX - Engineer",
  "description": "UX - Engineer",
  "location": { "city": "San Jose", "state": "CA", "country": "USA"},
  "tags": ["Dev","UX"],
  "hosted_url": "https://demoaccount.recruiterbox.com/jobs/ad3e",
  "allows_remote": true,
  "position_type": "full_time",
  "team": "FrontEnd Engineer"
}

This endpoint retrieves a specific opening.

HTTP Request

GET https://jsapi.recruiterbox.com/v1/openings/{id}/

Query Parameters

Parameter Description
client_name The client name eg: recruiterbox (mandatory)

URL Parameters

Parameter Description
id ID of the opening to retrieve

Get application form fields of a Opening

$.ajax({
  url: 'https://jsapi.recruiterbox.com/v1/openings/a42f3/application_form?client_name=demoaccount',
  contentType: 'application/json',
  success: function(response) {
      console.log(response);
    }
  });

The above snippet logs the JSON response like the example below

{
    "objects": [
        {
            "label": "First Name",
            "choices": [],
            "key": "candidate_first_name",
            "position": 0,
            "is_required": true,
            "type": "small_text"
        },
        {
            "label": "Last Name",
            "choices": [],
            "key": "candidate_last_name",
            "position": 1,
            "is_required": false,
            "type": "small_text"
        },
        {
            "label": "Email",
            "choices": [],
            "key": "candidate_email",
            "position": 2,
            "is_required": true,
            "type": "email"
        },
        {
            "label": "Phone",
            "choices": [],
            "key": "candidate_phone",
            "position": 3,
            "is_required": true,
            "type": "small_text"
        },
        {
            "label": "Resume",
            "choices": [],
            "key": "resume",
            "position": 4,
            "is_required": false,
            "type": "file"
        },
        {
            "label": "Age",
            "choices": [
                "18 - 25",
                "26 - 32",
                "33+"
            ],
            "key": "age",
            "position": 5,
            "is_required": false,
            "type": "select_one"
        }
    ],
    "meta": {
        "total": 6,
        "limit": 6,
        "offset": 0
    }
}

This endpoint retrieves all application form fields of a specific opening.

HTTP Request

GET https://jsapi.recruiterbox.com/v1/openings/{id}/application_form

Attributes

Attribute Description
key string A unique key for the field.
type string Type of the field, can be either of small_text, large_text, select_one, select_multiple, url, email, number, date & file.
is_required boolean Is a required field ?
label string Field label
choices list Choices for field, if either of type select_one or select_multiple

Query Parameters

Parameter Description
client_name The client name eg: recruiterbox (mandatory)

URL Parameters

Parameter Description
id ID of the opening

Field types

Type Description
small_text Single line text
large_text Paragraph text
select_one Applicants choose one option from a list
select_multiple Applicants can choose multiple options
url Web-link / URL
email Email Address
number Number
date Date
file File Upload

Apply for a Opening

var payload = {
  "fields": [
    { "key" : "candidate_first_name", "value" : "John"},
    { "key" : "candidate_last_name", "value" : "Doe"},
    { "key" : "candidate_email", "value" : "john.doe@gmail.com"},
    { "key" : "candidate_phone", "value" : "123"},
    { "key" : "resume", "value": {
      "encoded_data" : "aGVsbG8gd29ybGQ=",
      "file_name" : "resume.txt"
      }
    }
  ]
};


$.ajax({
  url: 'https://jsapi.recruiterbox.com/v1/openings/a42f3/apply?client_name=demoaccount',
  data: JSON.stringify(payload),
  dataType: 'json',
  contentType: 'application/json',
  type: 'POST',
  success: function(response) {
    console.log("success");
  }
});

The above snippet returns empty response on success with a status code 201 and logs success in the console.

This endpoint lets you apply to an opening. The end result is a candidate assigned to this opening.

HTTP Request

POST https://jsapi.recruiterbox.com/v1/openings/{id}/apply

Query Parameters

Parameter Description
client_name The client name eg: recruiterbox (mandatory)

URL Parameters

Parameter Description
id ID of the opening

Post data

Post data is a JSON with a required attribute fields and an optional attribute source. fields is a list of candidate attributes, while source can be (optionally) set to the source of this candidate.

Each item in fields has attributes key and value. The key can be ascertained from the application_form GET api of the opening for that field. The value must adhere to the following constraints based on the field type in the application_form GET api

Field Type Data
small_text Plain text with max char length of 200 eg: {"key":"candidate_first_name", "value":"John" }
large_text Paragraph text eg: {"key":"cover_letter", "value":"About me .." }
select_one Applicants choose one option from a list, option selected should be given as a value eg: {"key":"age", "value":"18 - 25" }
select_multiple Applicants can choose multiple options, options selected should be given as a list eg: {"key":"programming_expertise", "value":["python", "ruby", "js"]}
url Web-link / URL eg: {"key":"github_url", "value":"http://github.com/johndoe"}
email Email Address eg: {"key": "email", "value": "john.doe@gmail.com"}
number Number eg: {"key": "years_of_exp", "value": "5"}
file File should be in base64 encoded format Know more here eg: {"key": "resume", "value": {"encoded_data": "aGVsbG8gd29ybGQ=", "file_name": "resume.txt" }}

Validation errors on Post

Validation errors are a list within the attribute errors for each field key.

var payload = {
  "fields": [
    { "key" : "candidate_last_name", "value" : "Doe"},
    { "key" : "candidate_phone", "value" : "123"},
    { "key" : "resume", "value": {
      "encoded_data" : "wrong data posted",
      "file_name" : "resume.txt"
      }
    }
  ]
};


$.ajax({
  url: 'https://jsapi.recruiterbox.com/v1/openings/a42f3/apply?client_name=demoaccount',
  data: JSON.stringify(payload),
  dataType: 'json',
  type: 'POST',
  success: function(response) {
    console.log("success");
  },
  error: function(xhr, status, errors) {
    console.log(JSON.parse(xhr.responseText));
  }
});

The above command returns JSON structured like this: (response for bad request with status code 400)

  {
    "errors": [
      {"candidate_first_name": ["This is a required field"]},
      {"candidate_email": ["The email is not valid"]},
      {"resume": ["The file is not in base64 encoded format"]}
    ]
  }
Error Description
This is a disabled field The field is hidden / disabled, remove this field from post data
This is a required field This is a required field, candidate has to fill this field
The value is not in small_text format (>200 chars) -
The url is not valid -
The email is not valid -
The number is not valid -
The date is not in valid timestamp format -
The file is not in base64 encoded format The file should be encoded to base64 format. Know more here
The file_name should be specified with proper extension A proper extension should be given for file name
Not a valid file format. Allowed formats are ( doc, txt, html, htm, rtf, docx, odt, pdf ) Resume should be of those allowed formats.
Option should be a value for select_one e.g {‘key’:'somekey’, 'value’: '1’} -
Options should be in a list for select_multiple e.g {'key’:'somekey’, 'value’: ['1’, '2’]} -
No option selected No option was selected for a required select field
{field} is not a valid option {field} was not one of the choices listed in select_one / select_multiple.

Pagination

The “list” request for all top level API resources are paginated.

Query parameters

   
limit optional A limit on the number of objects returned. (default : 20, max: 250)
offset optional A cursor for use in pagination.

List response format

   
objects list Requested resource data
meta.total number Total count
meta.limit number Limit
meta.offset number Offset

Errors

Recruiterbox API uses standard HTTP response codes to indicate success or failure of an API request.

HTTP Code Meaning
200 OK - Request was successful
201 Created - The resource was created successfully.
204 No Content - In case of DELETE request, resource was deleted
400 Bad Request – Often missing a required parameter or specifying a wrong parameter
401 Unauthorized – Your API key is wrong
403 Forbidden – The resource requested is hidden for administrators only
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.