NAV
shell

Authentication

Example Request

curl https://api.recruiterbox.com/v1/openings -u {api_key}:

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password).

Authentication is done via the API key which you can find in Settings -> Advanced Settings -> API Key

Requests are authenticated using HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

You can see your API key, and revoke it if necessary. Be sure to keep your API key a secret. The API is designed to be used from server side.

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.

Openings

The Openings API lets you work on opening data for a client.

Attributes

Attribute Description
id string
title string
description string
location.city string
location.state string
location.country string
tags list
is_private boolean
is_archived boolean
application_email string
hosted_url string
created_on timestamp
modified_on timestamp
allows_remote boolean
position_type choice(contract, full_time, part_time)
team string
additional_fields json object
close_date integer

List of all Openings

curl https://api.recruiterbox.com/v1/openings \
 -u {api_key}:

The above command returns JSON structured like this:

{
    "objects": [
      {
        "id": "a42f3",
        "title": "UX - Engineer",
        "description": "UX - Engineer",
        "location": {
          "city": "San Jose",
          "state": "CA",
          "country": "USA"
        },
        "tags": ["Dev","UX"],
        "is_private": false,
        "is_archived": false,
        "application_email": "demoaccount-DMCC0203@app.recruiterbox.com",
        "hosted_url": "https://demoaccount.recruiterbox.com/jobs/ad3e",
        "created_on": 1413437038,
        "modified_on": 1413445073,
        "close_date": 1513445073,
        "allows_remote": true,
        "position_type": "contract",
        "team": "FrontEnd Engineers",
        "additional_fields": {
          "experience": "2"
        }
      }
    ],
    "meta": {
      "total_count":1,
      "limit": 20,
      "offset": 0
    }
}

This endpoint retrieves all openings.

HTTP Request

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

Query Parameters

Parameter Description
tags Filter by tags
city Filter by city
state Filter by state
country Filter by country
title Filter by title
description Filter by description
is_archived Filter by archived openings
is_private Filter by private / public openings
created_on__gt Filter by created date greater than a given timestamp
modified_on__gt Filter by modified date greater than a given timestamp
created_on__lt Filter by created date lesser than a given timestamp
modified_on__lt Filter by modified date lesser than a given timestamp
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

curl https://api.recruiterbox.com/v1/openings/a42f3 \
  -u {api_key}:

The above command returns JSON structured like this:

{
  "id": "a42f3",
  "title": "UX - Engineer",
  "description": "UX - Engineer",
  "location": { "city": "San Jose", "state": "CA", "country": "USA"},
  "tags": ["Dev","UX"],
  "is_private": false,
  "is_archived": false,
  "application_email": "demoaccount-DMCC0203@app.recruiterbox.com",
  "hosted_url": "https://demoaccount.recruiterbox.com/jobs/ad3e",
  "created_on": 1413437038,
  "modified_on": 1413445073,
  "close_date": 1513445073,
  "allows_remote": true,
  "position_type": "full_time",
  "team": "FrontEnd Engineer",
  "additional_fields": {
    "experience": "2"
  }
}

This endpoint retrieves a specific opening.

HTTP Request

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

URL Parameters

Parameter Description
id ID of the opening to retrieve

Note: In order to get the ‘id’ call the list of all openings (above) - which will return the ‘id’ parameter in the response.

Get application form fields of a Opening

curl https://api.recruiterbox.com/v1/openings/a42f3/application_form \
  -u {api_key}:

The above command returns JSON structured like this:

{
    "objects": [
        {
            "is_disabled": false,
            "label": "First Name",
            "choices": [],
            "key": "candidate_first_name",
            "position": 0,
            "is_required": true,
            "type": "small_text"
        },
        {
            "is_disabled": false,
            "label": "Last Name",
            "choices": [],
            "key": "candidate_last_name",
            "position": 1,
            "is_required": false,
            "type": "small_text"
        },
        {
            "is_disabled": false,
            "label": "Email",
            "choices": [],
            "key": "candidate_email",
            "position": 2,
            "is_required": true,
            "type": "email"
        },
        {
            "is_disabled": true,
            "label": "Phone",
            "choices": [],
            "key": "candidate_phone",
            "position": 3,
            "is_required": true,
            "type": "small_text"
        },
        {
            "is_disabled": false,
            "label": "Resume",
            "choices": [],
            "key": "resume",
            "position": 4,
            "is_required": false,
            "type": "file"
        },
        {
            "is_disabled": false,
            "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://api.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_disabled boolean Is a disabled field ?
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

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

curl -H "Content-Type: application/json" -X POST -d '{
  "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"
      }
    }
  ],
  "source" : "new website"
  }' https://api.recruiterbox.com/v1/openings/a42f3/apply -u {api_key}:

The above command returns empty response on success with a status code 201.

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

HTTP Request

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

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.

curl -H "Content-Type: application/json" -X POST -d '{
  "fields": [
    { "key" : "candidate_last_name", "value" : "Doe"},
    { "key" : "candidate_email", "value" : "john.doegmail.com"},
    { "key" : "candidate_phone", "value" : "123"},
    { "key" : "resume", "value": {
      "encoded_data" : "wrong data",
      "file_name" : "resume.txt"
      }
    }
  ],
  "source" : "new website"
  }' https://api.recruiterbox.com/v1/openings/a42f3/apply -u {api_key}:

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.
shell