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/v3/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/v3/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.

Parsing a resume

Example call (resume parsing and tagging profile)

curl -H "Authorization: Bearer <token>" \
-F 'file=@/absolute/path/to/pdf_file.pdf' \
-F 'filter=interviewed,applied_via_web' \
-F 'filters_geo_location=51.5074,0.1278' \
`` 

"https://opening.io/api/api/v3/process-resume"

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",
                "summary":"<resume_summary>",
                "address":{
                    "country": "",
                    "city": "",
                    "street": "",
                    "region":"Dublin"
                },
                "emails":["email@email.com"],
                "links":[],
                "raw_text":"<resume_text>",
                "experience":[
                    {
                        "company":"Company A",
                        "location":"Dublin",
                        "from":"01/12/2013",
                        "to":"01/08/2014",
                        "title":"Receptionist"
                    },
                    ..
                ],
                "education":[
                    {
                        "date":"01/04/2016",
                        "institution":"Dublin Business School",
                        "from":"01/09/2015",
                        "to":"01/04/2016",
                        "type":"university"
                    }
                    ..
                ],
                "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"
                    }
                    ..
                ],
                "extra_entities": {
                    "name": [
                        {
                            "count": 1,
                            "entity": "Phil Anselmo"
                        }
                        ..
                    ],
                    "position": [
                        {
                            "count": 1,
                            "entity": "Senior Java Developer"
                        }
                    ],
                    "company": [
                        {
                            "count": 1,
                            "entity": "Hewlett Packard"
                        }
                    ],
                    "city": [
                        {
                            "count": 1,
                            "entity": "Los Angeles"
                        }
                    ],
                    "country": [
                        {
                            "count": 1,
                            "entity": "Ireland"
                        }
                    ],
                    "university": [
                        {
                            "count": 1,
                            "entity": "Dublin City University"
                        }
                    ],
                    "academic-major": [
                        {
                            "count": 1,
                            "entity": "English Literature"
                        }
                    ],
                    "academic-degree": [
                        {
                            "count": 1,
                            "entity": "Ph.D"
                        }
                    ],
                    "academic-title": [
                        {
                            "count": 1,
                            "entity": "Adjunct Research Assistant Professor"
                        }
                    ]
                },
                "payscales": {
                    "salary_min_human_readable":"46k",
                    "salary_min":"46299",
                    "salary_max":"56406",
                    "salary_max_human_readable":"56k"
                },
                "github_data":{},
                "abilities": ["Software development","Project management"],
                    ..
                "last_updated":"2017-04-25T13:25:45+02:00",
    }
}

This endpoint allows you to parse a resume (.doc/.pdf file) into structured json data. Additionally, providing a list of tags to be linked with the resume allows filtering of profiles based on these tags later, when searching information.

HTTP Request

POST https://opening.io/api/api/v3/process-resume

POST Data

Parameter Type Default Description
file binary File contents (from a form submission or loaded from disk)
filter String Filter values separated by comma
filters_geo_location String Latitude,Longitude

or

Parameter Type Default Description
file binary File contents (from a form submission or loaded from disk)
filters String Multiple filters separated by a pipe charater with each filter’s values separated by comma
filters_geo_location String Latitude,Longitude

Geo-location

By specifying a set of lat/lon coordinates with the post request (both of type float64, expressed as a post parameter, separated by comma) you have the ability to geo-tag candidates thus later surface matching profiles around particular locations of interest (distance expressed in miles around a particular location, eq. candidates over a distance of maximum 50mi around London).

file [binary_blob]

filter interviewed,applied_via_web

or

file [binary_blob]

filters my_filter_1=argentina,china|my_filter_2=blue,green,red

or

file [binary_blob]

filters_geo_location 51.5074,0.1278

Listing of all account resumes

Example call (listing resumes)

curl "https://opening.io/api/v3/resumes/list/<page>/<records_limit>"
  -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_limit you can paginate data to suit your workflow. These parameters are both optional.

HTTP Request

GET https://opening.io/api/v3/resumes/list/<page>/<records_limit>

Query Parameters

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

Retrieving a complete resume profile

Example call (retrieving a particular resume)

curl "https://opening.io/api/v3/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/v3/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/api/v3/download/<id>

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

HTTP Request

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

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

Updating resume data

Example call (updating a particular resume)

curl "https://opening.io/api/v3/update/resume"
  -H "Authorization: Bearer <token>"
  -d '{
        "id" : '',
        "fields": {
            "candidate_name": 'new candidate name'
        },
        "filters": [
            {
                "name": 'my_filter_1',
                "values": 'mexico'
            },
            {
                "name": 'my_filter_2',
                "values": 'blue'
            }
        ]
    }'

The above command returns JSON structured like this:

{
    "success":true,
}

Updating of various fields (candidate_name, experience, filters, ..) for a particular candidate profile referred to by its resume ID.

HTTP Request

POST https://opening.io/api/v3/update/resume

Request parameters

Parameter Type Default Description
id String "" Resume ID to update
fields Object Field names and values to update
filters [Object, Object] Filter names and values to update

fields

The fields parameter allows specifiying of fields to update within the resume object:

Parameter Values
fields { 'candidate_name': 'new candidate name', 'other_field': 'new value' }

filters

The filters parameter allows updating of resume filters:

Parameter Values
filters [ { name: 'my_filter_1', values: 'mexico' }, { name: 'my_filter_2', values: 'blue' } ]

Deleting resumes

Example call

curl "https://opening.io/api/v3/delete/resume"
  -H "Authorization: Bearer <token>"
  -d '{
        "id" : '<resume_id>'
    }'

The above command returns JSON structured like this:

{
    "success":true,
}

Permanently removes a resume.

HTTP Request

POST https://opening.io/api/v3/delete/resume

Request parameters

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

Deleting resumes in bulk

Example call

curl "https://opening.io/api/v3/resumes/bulk-delete"
  -H "Authorization: Bearer <token>"
  -d '{
        "ids" : ['<resume_id>','<resume_id>']
    }'

The above command returns JSON structured like this:

{
    "success":true,
}

Permanently removes a list of resumes.

HTTP Request

POST https://opening.io/api/v3/resumes/bulk-delete

Request parameters

Parameter Type Default Description
ids Array [] Resume IDs to remove

Full text search

Example call unfiltered

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

Example call returning profiles tagged ‘applied_via_web’

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

Example call excluding profiles tagged ‘interviewed’

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

Example call including profiles tagged with multiple categories of filters

curl -XPOST 'https://opening.io/api/v3/resumes/search'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "query" : 'joanna smith',
        "fields": ['raw_text','candidate_name'],
        "filters": [
            {
                "name": 'my_filter_1',
                "values": 'argentina'
            },
            {
                "name": 'my_filter_2',
                "values": 'green,red'
            }
        ]
    }'

The above commands return 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/v3/resumes/search

JSON post data

{ "query" : String, "fields" : [String, String, ..], "include_filters": String, "exclude_filters": String, "filters": [Object, Object], }

JSON Parameters

Parameter Type Default Description
query String "" The search query
fields Array ["candidate_name","raw_text"] Fields to search
include_filters String Include only profiles tagged with a set of labels
exclude_filters String Exclude profiles tagged with a set of labels
filters Array Include only profiles tagged with a set of labels (multiple user-defined categories of filters)

Parameter values explained: fields

Value Explanation
raw_text Include complete resume contents to the search criteria
candidate_name Include candidate name to the search criteria
candidate_position Include candidate title (role) to the search criteria
candidate_location Include candidate location to the search criteria
candidate_skills Include candidate skills to the search criteria
company Include companies the candidate has been involved with to the search criteria
company_location Include locations of companies the candidate has been involved with to the search criteria

include_filters / exclude_filters

Values for include_filters / exclude_filters are strings containing tags separated by comma:

Parameter Values
include_filters interviewed,final_selection
exclude_filters argentina_office,junior_candidates

filters

The filters parameter allows filtering on multiple categories of user-defined tags:

Parameter Values
filters [ { name: 'my_filter_1', values: 'argentina' }, { name: 'my_filter_2', values: 'green,red' } ]

Matching candidates to jobs

Surfacing relevant candidates for a job description

Example call: the response_keys parameter can be used to cherry-pick particular keys of interest to be returned with each resume (as opposed to default behaviour which returns complete resume data):

curl -XPOST 'https://opening.io/api/v3/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,
        "response_keys": ['id','score']
    }'

Example call returning profiles matching a particular job (specified by its id).

curl -XPOST 'https://opening.io/api/v3/resumes/matching/job'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "job_id" : 'job_id'
    }'

Example call returning profiles tagged ‘applied_via_web’

curl -XPOST 'https://opening.io/api/v3/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
        "include_filters": 'applied_via_web',
    }'

Example call excluding profiles tagged ‘interviewed’

curl -XPOST 'https://opening.io/api/v3/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
        "exclude_filters": 'interviewed',
    }'

Example call including profiles tagged with multiple categories of filters

curl -XPOST 'https://opening.io/api/v3/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
        "filters": [
            {
                "name": 'my_filter_1',
                "values": 'argentina'
            },
            {
                "name": 'my_filter_2',
                "values": 'green,red'
            }
        ]
    }'

Profiles located around London with a radius range of maximum 50 miles:

curl -XPOST 'https://opening.io/api/v3/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
        "filters": [
            {
                "type": 'geo_location',
                "name": 'geo_location',
                "values": {
                    "lat": 51.5074,
                    "lon": 0.1278,
                    "distance": 50
                }
            },
        ]
    }'

Example call returning profiles containing keywords ‘ipma’ and ‘dublin’. Both keywords must exist in text.

curl -XPOST 'https://opening.io/api/v3/resumes/matching/job'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "job_title" : 'Senior software developer',
        "job_description": "..",
        "nice_to_haves": { "text": "ipma,dublin", "match": "all" }
    }'

Example call returning profiles containing any (or multiple) keywords (relaxed restrictions)

curl -XPOST 'https://opening.io/api/v3/resumes/matching/job'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "job_title" : 'Senior software developer',
        "job_description": "..",
        "nice_to_haves": { "text": "ipma,dublin", "match": "any" }
    }'

The above commands return 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)

Filtering results

You can use filters, include_filters, exclude_filters parameters to enable filtering of profiles matching a particular set of tags.

Restricting matching to a particular geographic location

By including a particular filter (named geo_location) with the filters array you can restrict matches to a particular geographic location defined by its latitude / longitude coordinates and a radius in miles.

Must-have skills

There may exist a scenario when you need to restrict matching only for resumes containing special keywords, for instance a particular type of accreditation (eq.: “IPMA”). By appending a nice_to_haves parameter with your query you can define such keyword restrictions.

HTTP Request

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

JSON post data

{ job_title : string, job_description : string, title_influence : int, job_description_influence : int include_filters: string, exclude_filters: string, filters: [object, object], nice_to_haves: object response_keys: [field, field] }

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
include_filters String Include only profiles tagged with a set of labels
exclude_filters String Exclude profiles tagged with a set of labels
filters Array Include only profiles tagged with a set of labels (multiple user-defined categories of filters)
nice_to_haves Object Include only profiles containing particular keywords
response_keys Array All fields Include only particular fields from each resume object. id and score will always be returned

Alternatively for convenience (if a particular job is already stored with opening) you can employ its job_id directly in order to surface candidates - in this case job_title / job_description will be ignored (no longer required as they’re superseded by job_id):

Parameter Type Default Description
job_id String "" Job ID

include_filters / exclude_filters

Values for include_filters / exclude_filters are strings containing tags separated by comma:

Parameter Values
include_filters interviewed,final_selection
exclude_filters argentina_office,junior_candidates

filters

The filters parameter allows filtering on multiple categories of user-defined tags:

Parameter Values
filters [ { name: 'my_filter_1', values: 'argentina' }, { name: 'my_filter_2', values: 'green,red' } ]

Geo location restrictions

The geo_location filter added as a child of the filters parameter allows restricting matches to a particular geographic location defined by its latitude / longitude coordinates and a radius in miles.

Parameter Values
filters [ { type: 'geo_location', name: 'geo_location', values: { lat: 51.5074, lon: 0.1278, distance: 50 } }, .. ]

nice_to_haves

The nice_to_haves parameter allows filtering resumes containing particular keywords (separate multiple keywords by a comma). The match key can only have one of the two values: any (at least one keyword must match) / all (all keywords must match):

Parameter Values
nice_to_haves { text: 'ipma, other_keyword', match: 'any'}
nice_to_haves { text: 'ipma, other_keyword', match: 'all'}

Job-candidate similarity scores

Example call

curl -XPOST 'https://opening.io/api/v3/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/v3/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 for unfiltered results

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

Example call returning profiles tagged ‘applied_via_web’

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

Example call excluding profiles tagged ‘interviewed’

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

Example call including profiles tagged with multiple categories of filters

curl -XPOST 'https://opening.io/api/v3/resumes/matching/resume'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "id" : "<id>",
        "title_influence": 40,
        "content_influence": 60
        "filters": [
            {
                "name": 'my_filter_1',
                "values": 'argentina'
            },
            {
                "name": 'my_filter_2',
                "values": 'green,red'
            }
        ]
    }'

The above commands return 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.

Filtering results

You can use filters, include_filters, exclude_filters parameters to enable filtering of profiles matching a particular set of tags.

HTTP Request

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

JSON post data

{ "id" : string, "title_influence" : int, "content_influence" : int "include_filters": string, "exclude_filters": string, "filters": [object, object], }

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
include_filters String Include only profiles tagged with a set of labels
exclude_filters String Exclude profiles tagged with a set of labels
filters Array Include only profiles tagged with a set of labels (multiple user-defined categories of filters)

Jobs recommendations

Suggested jobs for candidates

Example call for unfiltered job posts

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

Example call returning job posts tagged ‘ireland’

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

Example call excluding job posts tagged ‘inactive’

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

Example call including job posts tagged with multiple categories of filters

curl -XPOST 'https://opening.io/api/v3/jobs/matching/candidate'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "id" : "<id>",
        "title_influence": 40,
        "content_influence": 60
        "filters": [
            {
                "name": 'source',
                "values": 'a_particular_job_board'
            },
            {
                "name": 'my_tags',
                "values": 'equal_opportunities'
            }
        ]
    }'

Example call including job posts geo-tagged around London with a radius range restriction of maximum 50 miles:

curl -XPOST 'https://opening.io/api/v3/jobs/matching/candidate'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "id" : "<id>",
        "title_influence": 40,
        "content_influence": 60
        "filters": [
            {
                "type": 'geo_location',
                "name": 'geo_location',
                "values": {
                    "lat": 51.5074,
                    "lon": 0.1278,
                    "distance": 50
                }
            },
        ]
    }'

The above commands return JSON structured like this:

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

The job suggestions API enables recommending of suitable job posts for a particular candidate.

Filtering results

You can use filters, include_filters, exclude_filters parameters to enable filtering of profiles matching a particular set of tags.

HTTP Request

POST https://opening.io/api/v3/jobs/matching/candidate

JSON post data

    {  
     `id` : string,  
     `include_filters`: string,  
     `exclude_filters`: string,  
     `filters`: [object, object],  
    }  

JSON Parameters

Parameter Type Default Description
id String "" Resume ID to recommend jobs for
include_filters String Include only profiles tagged with a set of labels
exclude_filters String Exclude profiles tagged with a set of labels
filters Array Include only profiles tagged with a set of labels (multiple user-defined categories of filters)
response_keys Array All fields Include only particular fields from each job object. id and score will always be returned

include_filters / exclude_filters

Values for include_filters / exclude_filters are strings containing tags separated by comma:

Parameter Values
include_filters ireland
exclude_filters inactive

filters

The filters parameter allows filtering on multiple categories of user-defined tags:

Parameter Values
filters [ { name: 'source', values: 'a_particular_job_board' }, { name: 'my_filter_2', values: 'green,blue' } ]

Geo location restrictions

The geo_location filter added as a child of the filters parameter allows restricting matches to a particular geographic location defined by its latitude / longitude coordinates and a radius in miles.

Parameter Values
filters [ { type: 'geo_location', name: 'geo_location', values: { lat: 51.5074, lon: 0.1278, distance: 50 } }, .. ]

nice_to_haves

The nice_to_haves parameter allows filtering jobs containing particular keywords (separate multiple keywords by a comma). The match key can only have one of the two values: any (at least one keyword must match) / all (all keywords must match):

Parameter Values
nice_to_haves { text: 'ipma, other_keyword', match: 'any'}
nice_to_haves { text: 'ipma, other_keyword', match: 'all'}

Jobs similar to each other

Example call for unfiltered results

curl -XPOST 'https://opening.io/api/v3/jobs/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
    }'

Example call returning job posts tagged ‘ireland’

curl -XPOST 'https://opening.io/api/v3/jobs/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
        "include_filters": 'ireland',
    }'

Example call excluding job posts tagged ‘inactive’

curl -XPOST 'https://opening.io/api/v3/jobs/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
        "exclude_filters": 'inactive',
    }'

Example call including job posts tagged with multiple categories of filters

curl -XPOST 'https://opening.io/api/v3/jobs/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
        "filters": [
            {
                "name": 'source',
                "values": 'a_particular_job_board'
            },
            {
                "name": 'my_tags',
                "values": 'equal_opportunities'
            }
        ]
    }'

The above commands return JSON structured like this:

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

Identification and retrieval of jobs similar to each other.

Filtering results

You can use filters, include_filters, exclude_filters parameters to enable filtering of profiles matching a particular set of tags.

HTTP Request

POST https://opening.io/api/v3/jobs/matching/job

JSON post data

{ "job_title" : string, "job_description" : string, "include_filters": string, "exclude_filters": string, "filters": [object, object], }

JSON Parameters

Parameter Type Default Description
job_title String "" Job title
job_description String "" Job description
include_filters String Include only profiles tagged with a set of labels
exclude_filters String Exclude profiles tagged with a set of labels
filters Array Include only profiles tagged with a set of labels (multiple user-defined categories of filters)

include_filters / exclude_filters

Values for include_filters / exclude_filters are strings containing tags separated by comma:

Parameter Values
include_filters interviewed,final_selection
exclude_filters argentina_office,junior_candidates

filters

The filters parameter allows filtering on multiple categories of user-defined tags:

Parameter Values
filters [ { name: 'my_filter_1', values: 'argentina' }, { name: 'my_filter_2', values: 'green,red' } ]

Creating jobs

Example call - no filters specified

curl "https://opening.io/api/v3/jobs/create"
  -H "Authorization: Bearer <token>"
  -d '{
        "jobs": [
            {
                "title": 'job title 1'
                "description": 'job description 1'
            },
            {
                "title": 'job title 2'
                "description": 'job description 2'
            },
            ...
        ]
    }'

Example call - with filters specified

curl "https://opening.io/api/v3/jobs/create"
  -H "Authorization: Bearer <token>"
  -d '{
        "jobs": [
            {
                "title": 'job title 1',
                "description": 'job description 1',
                "filters": [
                    {
                        "name": 'source',
                        "values": 'job_board'
                    },
                    {
                        "name": 'my_tags',
                        "values": 'inclusion'
                    }
                ]
            },
            {
                "title": 'job title 2'
                "description": 'job description 2'
                "filters": [
                    {
                        "name": 'source',
                        "values": 'a_different_job_board'
                    },
                    {
                        "name": 'my_tags',
                        "values": 'diversity,inclusion'
                    }
                ]
            },
            ...
        ]
    }'

Example call - with geo-location information

curl "https://opening.io/api/v3/jobs/create"
  -H "Authorization: Bearer <token>"
  -d '{
        "jobs": [
            {
                "title": 'job title 1',
                "description": 'job description 1',
                "filters_geo_location": {'lat': 51.5074, 'lon': 0.1278},
            },
            {
                "title": 'job title 2',
                "description": 'job description 2',
                "filters_geo_location": {'lat': 51.5074, 'lon': 0.1278},
            },
            ...
        ]
    }'

The above command returns JSON structured like this:

{
    "success":true,
    "data": {
        "jobs": [
            {
                "title": 'job title 1',
                "id": 'unique_id_1'
            },
            {
                "title": 'job title 2',
                "id": 'unique_id_2'
            }
        ]
    }
}

Creating jobs in bulk.

HTTP Request

POST https://opening.io/api/v3/jobs/create

Request parameters

Parameter Type Default Description
jobs [Object, Object] An array of job objects

Job objects

Each job will be represented as a json object containing at minimum two non-empty properties: title and description. Additional fields are accepted and will be preserved, being returned as a meta property of response job object when invoking the /api/v3/job/<id> or /api/v3/jobs/list endpoints.

Parameter Values
job { 'title': 'marketing manager', 'description': '', .. }

filters

A filters property added with each job allows defining of filters:

Parameter Values
filters [ { name: 'source', values: 'a_different_job_board' }, { name: 'my_tags', values: 'diversity' } ]

geo-location

A filters_geo_location property added with each job allows geo-tagging any particular job. Following geo-tagging you have the ability surface relevant jobs for any particular profile, restricting matching jobs around particular locations of interest.

Parameter Values
filters_geo_location { 'lat': 51.5074, 'lon': '0.1278' }

Retrieving a job

Example call (retrieving a particular resume)

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

The above command returns JSON structured like this:

{
    "success":true,
    "result":
        {
            "data": {
                "title": '..',
                "description": '..',
                ...
            }
    }
}

The following endpoint enables access to a job object in json format:

HTTP Request

GET https://opening.io/api/v3/job/<id>

URL Parameters

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

Listing all jobs

Example call (listing jobs)

curl "https://opening.io/api/v3/jobs/list/<page>/<records_limit>"
  -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "page": 1,
        "records": 20,
        "data": [
          {
            job_object
          },
          {
            job_object
          },
          ..
        ]
    }
}

A listing of jobs stored in your account is available by querying the endpoint below. By specifying extra parameters like page and records_limit you can paginate data to suit your workflow. These parameters are both optional.

HTTP Request

GET https://opening.io/api/v3/jobs/list/<page>/<records_limit>

Query Parameters

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

Updating jobs data

Example call - no filters specified

curl "https://opening.io/api/v3/update/job"
  -H "Authorization: Bearer <token>"
  -d '{
        "id" : '',
        "fields": {
            "description": 'updated job description'
        }
    }'

Example call (updating a particular job) - with filters specified

curl "https://opening.io/api/v3/update/job"
  -H "Authorization: Bearer <token>"
  -d '{
        "id" : '',
        "fields": {
            "description": 'updated job description'
        },
        "filters": [
            {
                "name": 'source',
                "values": 'a_different_job_board'
            },
            {
                "name": 'my_tags',
                "values": 'diversity,inclusion'
            }
        ]
    }'

The above command returns JSON structured like this:

{
    "success":true,
}

Updating of various fields (title, description, filters, ..) for a particular job post referred to by its job ID.

HTTP Request

POST https://opening.io/api/v3/update/job

Request parameters

Parameter Type Default Description
id String "" Resume ID to update
fields Object Field names and values to update
filters [Object, Object] Filter names and values to update

fields

The fields parameter allows specifiying of fields to update within the job object:

Parameter Values
fields { 'title': 'marketing manager', 'description': '', .. }

filters

The filters parameter allows updating of job filters:

Parameter Values
filters [ { name: 'source', values: 'a_different_job_board' }, { name: 'my_tags', values: 'diversity' } ]

Updating data for multiple jobs

Example call - no filters specified

curl "https://opening.io/api/v3/update/jobs"
  -H "Authorization: Bearer <token>"
  -d '{
        "ids" : ['id_job_1','id_job_2',..],
        "fields": {
            "description": 'updated job description'
        }
    }'

Example call (updating multiple jobs) - with filters specified

curl "https://opening.io/api/v3/update/jobs"
  -H "Authorization: Bearer <token>"
  -d '{
        "ids" : ['job_a','job_b'],
        "fields": {
            "description": 'updated job description'
        },
        "filters": [
            {
                "name": 'source',
                "values": 'a_different_job_board'
            },
            {
                "name": 'my_tags',
                "values": 'diversity,inclusion'
            }
        ]
    }'

The above command returns JSON structured like this:

{
    "success":true,
}

Updating of various fields (title, description, filters, ..) for multiple job posts at once referred to by their job IDs.

HTTP Request

POST https://opening.io/api/v3/update/jobs

Request parameters

Parameter Type Default Description
ids Array(String) [] Job ids (array of strings) to update
fields Object Field names and values to update
filters [Object, Object] Filter names and values to update

fields

The fields parameter allows specifiying of fields to update within the job object:

Parameter Values
fields { 'title': 'marketing manager', 'description': '', .. }

filters

The filters parameter allows updating of job filters:

Parameter Values
filters [ { name: 'source', values: 'a_different_job_board' }, { name: 'my_tags', values: 'diversity' } ]

Deleting jobs

Example call

curl "https://opening.io/api/v3/delete/job"
  -H "Authorization: Bearer <token>"
  -d '{
        "id" : '<job_id>'
    }'

The above command returns JSON structured like this:

{
    "success":true,
}

Permanently removes a job post.

HTTP Request

POST https://opening.io/api/v3/delete/job

Request parameters

Parameter Type Default Description
id String "" Job ID to remove

Deleting jobs in bulk

Example call

curl "https://opening.io/api/v3/jobs/bulk-delete"
  -H "Authorization: Bearer <token>"
  -d '{
        "ids" : ["<job_id>","job_id"]
    }'

The above command returns JSON structured like this:

{
    "success":true,
}

Permanently removes a list of job posts.

HTTP Request

POST https://opening.io/api/v3/jobs/bulk-delete

Request parameters

Parameter Type Default Description
ids Array [] Resume IDs to remove

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

Skills extraction and suggestions

Skills extraction

Example call

curl -XPOST 'https://opening.io/api/v2/extraction/skills'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "text" : 'Body of text',
        "suggest": true,
        "suggest_limit": 20
    }'

The above commands return JSON structured like this:

{
  "success": true,
  "result": {
    "data": {
      "skills": [
        {
          "label": "php",
          "score": 1
        },
        {
          "label": "mysql",
          "score": 1
        }
      ],
      "suggested_skills": [
        {
          "label": "xampp",
          "score": 1
        },
        {
          "label": "postgresql",
          "score": 0.6792452830188679
        },
        ...
      ]
    }
  }
}

This endpoint allows extraction of skills from text. For convenience it can also return newly suggested skills in the same response by appending a suggest parameter with your query and setting its value to true.

HTTP Request

POST https://opening.io/api/v2/extraction/skills

JSON post data

{ "text" : string, "suggest" : boolean, "suggest_limit" : integer }

JSON Parameters

Parameter Type Default Description
text String "" Body of text to extract skills from
suggest Boolean false Perform suggestion of skills together with extraction [optional]
suggest_limit Integer 15 Maximum number of suggested skills [optional]

Skills suggestions

Example call

curl -XPOST 'https://opening.io/api/v2/extraction/skills-suggestions'
  -H 'Authorization: Bearer <token>'
  -H 'Content-Type: application/json'
  -d '{
        "text" : "Body of text",
        "limit": 15
    }'

The above command returns JSON structured like this:

{
  "success": true,
  "result": {
    "data": {
      "suggested_skills": [
        {
          "label": "xampp",
          "score": 1
        },
        {
          "label": "postgresql",
          "score": 0.6792452830188679
        },
        ...
      ]
    }
  }
}

This endpoint allows suggestions of new sets of skills based on a given text (suggested skills will differ from the various skills we detect in text).

HTTP Request

POST https://opening.io/api/api/v2/extraction/skills-suggestions

JSON post data

{ "text" : string, "limit" : string }

JSON Parameters

Parameter Type Default Description
text String "" Body of text to extract skills from
limit Integer 15 Maximum number of suggested skills