NAV Navbar
Logo

Introduction

Welcome to the Opening API! You can use it to access underlying opening.io functionality in an automated fashion either from your web application directly or from within your internal tooling ecosystem. We aim to maintain a solid, stable and long-term API contract with future additional functionality branching out as new versioned APIs thus preserving existing functionality with zero code changes on your part.

All calls will return results in json format. This resulting object will always have two keys set unless explicitly stated otherwise: success (boolean) and result (object). HTTP error codes are also provided with the response.

Json result object

Key Type Possible values
success Boolean true / false
result Object “result”: { “data”: .. }
or
“result”: { “error”: String }

Authentication

Example call

curl "https://opening.io/api/v2/success"
  -H "Authorization: Bearer <token>"

Make sure to replace <token> with your secret token key.

Opening uses token-based authentication and OAuth 2.0 to allow access to the API. You can register a new API token at the following address: https://opening.io/developers.

Tokens are expected to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <token>

A number of APIs (search, matching, similarity, accounts in particular) require submission of JSON data when requesting results. In this case please make sure the request JSON object is valid and submitted using the correct HTTP request method (typically POST). Show some love and include a proper Content-Type: application/json header value if possible too with the request - though this is not a hard requirement.

Testing endpoint

For testing purposes the following endpoint is available to use in order to validate a correct request:

https://opening.io/api/v2/success

Resumes

Synopsis

We operate on non-numeric document IDs (strings) which offer absolutely no guarantees in terms of sequentiality (“a…”, “b..”, ..). These IDs however are guaranteed to be unique and consistent in time therefore reliable for storing locally on your end.

Listing of all account resumes

Example call (listing resumes)

curl "https://opening.io/api/v2/resumes/list/<page>/<records>"
  -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "page": 1,
        "records": 20,
        "data": [
          {
            "id": "..",
            "candidate_name": "Candidate one"
          },
          {
            "id": "..",
            "candidate_name": "Candidate two"
          },
          ..
        ]
    }
}

An index of resumes stored in your account is available by querying the endpoint below. By specifying extra parameters like page and records you can paginate data to suit your workflow. These parameters are both optional.

HTTP Request

GET https://opening.io/api/v2/resumes/list/<page>/<records>

Query Parameters

Parameter Type Default Description
page Integer 1 Page number to retrieve
records Integer 20 Number of records per page

Retrieving a complete resume profile

Example call (retrieving a particular resume)

curl "https://opening.io/api/v2/resume/<id>"
  -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "success":true,
    "result":
        {
            "data": {
                "id":"<resume_id>",
                "type":"resume",
                "pdf":"/download/<resume_id>",
                "phones":["+123 45 678 90"],
                "skills":["databases","c#","qa",..],
                "topics":[
                    {"score":0.212123,"name":"QA & Software testing"},
                    ...
                ],
                "candidate_name":"Joanna Smith",
                "raw_text":"<resume_text>",
                "emails":["email@email.com"],
                "education":[
                    {
                        "date":"01/04/2016",
                        "institution":"Dublin Business School",
                        "from":"01/09/2015",
                        "to":"01/04/2016",
                        "type":"university"
                    }
                    ..
                ],
                "experience":[
                    {
                        "company":"Company A",
                        "location":"Dublin",
                        "from":"01/12/2013",
                        "to":"01/08/2014",
                        "title":"Receptionist"
                    },
                    ..
                ],
                "links":[],
                "folio":[],
                "pdf_pages":[
                    "/resume-page/<id>/page-1",
                    "/resume-page/<id>/page-2"
                ],
                "social_profiles":[
                    {
                        "link":"https://ie.linkedin.com/in/profile_link",
                        "detected":"https://ie.linkedin.com/in/profile_link",
                        "type":"linkedin"
                    }
                    ..
                ],
                "payscales": {
                    "salary_min_human_readable":"46k",
                    "salary_min":"46299",
                    "salary_max":"56406",
                    "salary_max_human_readable":"56k"
                },
                "github_data":{},
                "summary":"<resume_summary>",
                "abilities": ["Software development","Project management"],
                    ..
                "address":{
                    "country": "",
                    "city": "",
                    "street": "",
                    "region":"Dublin"
                },
                "last_updated":"2017-04-25T13:25:45+02:00",
    }
}

The following endpoint enables access to a complete candidate profile object in json format:

HTTP Request

GET https://opening.io/api/v2/resume/<id>

URL Parameters

Parameter Type Default Description
id String "" Resume ID to retrieve

Should you require access to the physical resume file (.doc and/or .pdf) or screenshots of each individual page of the resume (.png) you have an extra set of supporting services available:

HTTP Request

File download

GET https://opening.io/download/<id>

Parameter Type Default Description
id String "" Resume ID to retrieve

HTTP Request

GET https://opening.io/resume-page/<id>/page-<page_id>

Parameter Type Default Description
id String "" Resume ID to retrieve
page_id String "" 1, 2, 3, ..

Full text search

Example call

curl -XPOST 'https://opening.io/api/v2/resumes/search'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "query" : "joanna smith",
        "fields": ["raw_text","candidate_name"]
    }'

The above command returns JSON structured like this:

{
    "success": true
    "data": [
        {resume data},
        {resume data}
        ..
}

The full text search API provides functionality to search resumes for full text matches, similar to a Google search. You can limit the scope of search to only include specific resume fields (tags, raw_text, candidate_name) as detailed below.

HTTP Request

POST https://opening.io/api/v2/resumes/search

JSON post data

{
"query" : String,
"fields" : [String, String, ..]
}

JSON Parameters

Parameter Type Default Description
query String "" The search query
fields Array ["tags","candidate_name","raw_text"] Fields to search

Parameters explained

Parameter Explanation
tags Include candidate tags (added by the recruiter) to the search criteria.
raw_text Include complete resume contents to the search criteria
candidate_name Include candidate name to the search criteria

Matching candidates to jobs

Example call

curl -XPOST 'https://opening.io/api/v2/resumes/matching/job'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "job_title" : "Senior software developer",
        "job_description": "..",
        "title_influence": 40,
        "job_description_influence": 60
    }'

The above command returns JSON structured like this:

{
    "success": true
    "data": [
        {resume data},
        {resume data}
        ..
}

The matching API allows surfacing of suitable candidates for a particular role together with matching scores. Besides accepting a job title / job description the API supports biasing of results towards one of the two criteria by introducing two controls for fine tuning search (optional):
title_influence and job_description_influence.

Biasing results

The biasing controls are named title_influence and job_description_influence with integer values in the 0-100 range. You can specify one, both or none at all thus reverting to default values. Their values should sum up to 100 (eq.: if title_influence has a value of 34 then value of job_description_influence will become 66 and viceversa)

Biasing allows you to surface candidates uniquely tailored to very specific job requirements
(eq. “sales manager” coupled with a pharma job description)

HTTP Request

POST https://opening.io/api/v2/resumes/matching/job

JSON post data

{
"job_title" : string,
"job_description" : string,
"title_influence" : int,
"job_description_influence" : int
}

JSON Parameters

Parameter Type Default Description
job_title String "" Job title
job_description String "" Job description
title_influence Integer 40 Title bias in search
job_description_influence Integer 60 Job description bias in search

Job-candidate similarity scores

Example call

curl -XPOST 'https://opening.io/api/v2/job/similarity-score/resume'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "job_title" : "Senior software developer",
        "job_description": "..",
        "id": ".."
    }'

The above command returns JSON structured like this:

{
    "success": true
    "data": {
            "score": int
        }
        ..
}

This endpoint returns a similarity score between a job and a particular candidate referred to by its id.

HTTP Request

POST https://opening.io/api/v2/job/similarity-score/resume

JSON post data

{
"job_title" : string,
"job_description" : string,
"id" : string
}

JSON Parameters

Parameter Type Default Description
job_title String "" Job title
job_description String "" Job description
id String "" Resume ID to compare job against

Score

score is an integer value with a range between 0 (completely dissimilar) and 100 (maximum compatibility)

Parameter Type Default Description
job_title String "" Job title
job_description String "" Job description
id String "" Resume ID to provide similarity score against

Surfacing similar candidates

Example call

curl -XPOST 'https://opening.io/api/v2/resumes/matching/resume'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "id" : "<id>",
        "title_influence": 40,
        "content_influence": 60
    }'

The above command returns JSON structured like this:

{
    "success": true
    "data": [
        {resume data},
        {resume data}
        ..
}

The similarity API enables quick surfacing of candidates similar to each other and/or matching scores between given sets of candidates. Identical to job matching API this endpoint also allows you to bias results towards one of the two criteria: experience (candidates titles) and resume content (sets of skills, abilities, latent contextual information). The controls allowing biasing are named title_influence and content_influence.

Biasing results

The fine tuning controls allowing biasing are title_influence and content_influence with integer values in the 0-100 range. You can specify one, both or none at all thus reverting to default values.

Their values should sum up to 100 (eq.: if title_influence has a value of 34 then value of content_influence will become 66 and viceversa)

Biasing allows you to surface candidates with similar titles (“senior java developer”) and/or similar abilities extracted from the resume content.

HTTP Request

POST https://opening.io/api/v2/resumes/matching/resume

JSON post data

{
"id" : string,
"title_influence" : int,
"content_influence" : int
}

JSON Parameters

Parameter Type Default Description
id String "" Resume ID to surface similar profiles for
title_influence Integer 40 Bias results towards profiles with similar job titles
content_influence Integer 60 Bias results towards profiles with similar resume content

Leaderboards

Example call

curl -XPOST 'https://opening.io/api/v2/resumes/leaderboards'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "topic" : "web-development",
    }'

The above command returns JSON structured like this:

{
    "success": true
    "data": [
        {resume data},
        {resume data}
        ..
}

Top talent in one click: leaderboards API enables talent discovery by providing quick access to ranked lists of best qualified candidates per area of interest ranging from Web Development to Systems Administration and Data Science.

HTTP Request

POST https://opening.io/api/v2/resumes/leadeboards

JSON post data

{
"topic" : string
}

JSON Parameters

Parameter Type Default Description
topic String "" Area of interest to surface rankings for

Accepted topic values

Value Description
databases Databases & Information Architecture
data-science Data Science & Artificial Intelligence
software-development Software development
mobile-development Mobile Development
design Design, Creative & Strategy
web-development Web Development & E-Commerce
qa QA & Software Testing
systems-administration Systems & Network Administration
release-management Release Management
marketing Marketing & Sales
business-development Business Development

Document processing

Synopsis

These are general-purpose services we use on our workflow of potential high value in your business requirements: instant generic document to pdf conversion (streamable and/or in batch), screenshotting of pdf pages, screenshotting of websites in bulk (several links at once).

A quick demo is available at this address: https://engineering.opening.io/demo.html

Document to PDF conversion

Submit the following form

<form method="POST" enctype="multipart/form-data"  
    action="http://convert.opening.io/doc-to-pdf">
    <div>
        <input type="file" name="file" placeholder="select a document..">
    </div>
    <div>
        <input type="submit" value="Get PDF version">
    </div>
</form>

HTTP Request

POST http://convert.opening.io/doc-to-pdf

Response of this query will contain the converted pdf file.

Screenshotting of PDF files

Submit the following form

<form method="POST" enctype="multipart/form-data"  
    action="http://convert.opening.io/pdf-to-img">
    <div>
        <input type="file" name="file" placeholder="select a document..">
    </div>
    <div>
        <input type="submit" value="Get screenshots">
    </div>
</form>

HTTP Request

POST http://convert.opening.io/pdf-to-img

Response of this query will contain a .zip file, all screenshots contained within.

Websites screenshotting

Submit the following form

<form method="POST"  
    action="http://convert.opening.io/visitor">  
    <div>  
        <textarea name="url" placeholder="Paste a couple of URLs.."></textarea>  
        Width: <input type="text" name="width" value="220"><br>
        Height: <input type="text" name="height" value="165"><br>
        Extract text contents: 
            <select name="extract_contents">
                <option value="">No</option>
                <option value="yes">Yes</option>
            </select>
    </div>
    <div>
        <input type="submit" value="Get screenshots">
    </div>
</form> 

HTTP Request

POST http://convert.opening.io/visitor

This enables extraction of website screenshots in bulk. Response will be a .zip file containing:

Post parameters explained

Value Description
url Website url (or list of urls in the same string)
width Screenshot width. Default: 220px
height Screenshot height. Default: 165px
extract_contents Extract website text contents too.
Values: yes/no
Default: no

Beta / locked APIs

Synopsis

These are APIs enabling a much richer platform interaction - instant resume parsing, jobs, shortlists, tagging and batch file processing.

For the time being they are under beta status or tight control - let us know about your needs and we’ll do our best to make things easy. Just keep in mind though that all document changes these APIs enable are consistent and permanent. Like, forever.

Thank you,

engineering@opening.io