Candidate Search API

The following information is for candidate resume search and retrieval integration. It describes the authentication method, the search types and the retrieval steps. 
 

Monster Semantic Technology

Monster ushered in a new performance standard with its proprietary 6Sense semantic technology. Unlike any other solution, 6Sense's intelligent search uses fuzzy logic and its extensive and hierarchical knowledge base of concepts to evaluate a candidate's amount, depth, length and recency of related work experience, education, relevant skills and location.

The main differentiators with 6Sense Search are the following:

1.     Conceptual Search Capability – 6Sense automatically translates your search criteria into related search terms to maximize overall search recall and effectiveness. This eliminates the need to enter and maintain a long list of keywords and ensures you always have access to the latest technology skills.

2.     Contextual Search Capability – The 6Sense Search engine uniquely categorizes the attributes of each candidate’s resume. That capability is used to score candidates by experience level and can differentiate between valuable recent skills versus ones from older jobs.

3.     Dynamic Candidate Scoring – Whenever you search for candidates, 6Sense stack-ranks your entire population of resumes in seconds. This gives you the unlimited ability to change your search criteria any number of times to score your valuable candidate data in real time.

4.     Automated Matching – JobDetail mode uses Monster’s technology to analyzes the job title and description to construct and execute a search based on critical skills found in the job description.


This API uses a Client ID and Client Secret that your Monster representative will provide you with.

client_id = CLIENTID

client_secret = CLIENTSECRET

 

Request

curl -X POST \

  https://sso.monster.com/core/connect/token \

  -H 'Content-Type: application/x-www-form-urlencoded' \

  -d 'client_id=CLIENTID&client_secret=CLIENTSECRET&scope=GatewayAccess&grant_type=client_credentials'

 

Response

{

  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJodHRwOi8vc2d6bFVnvAQJElIY'",

  "expires_in": 86400,

  "token_type": "Bearer"

}

The token is valid for 86,400 seconds (24 hours). It is supplied in an Authorization: bearer HTTP request header.

The root URL is POST: https://api.jobs.com/v2/candidates/queries.

 

Query Parameters

The search API supports paging in the GitHub style.

Paging parameters are supplied in the query string, as also may the "verbose" flag, which will return the actual resume document in the response.

1000 results is the maximum that Monster returns on any individual search. 

Parameter

Description

Type

Default

page

Page number to be retrieved.

integer

1

perPage

Items per page.

integer

20

verbose

If true, some extra information will be included in the response.
The original request (as passed by the caller) is included as the originalCriteria property.
If the original request was of jobDetail type, an object called searchCriteria is also returned.
This contains a property called equivalentSemanticSearch. This is the actual request used internally (having extracted skill information from the job title and description).
If the original request was a jobDetail type that used jobId, then two extra text fields (jobTitle and jobDescription) record the information about the job at the time the request was made.

boolean

false

 

Example Curl Search Request - showing paging parameters

 

curl -X POST \

  'https://api.jobs.com/v2/candidates/queries?page=1&perPage=10' \

  -H 'Accept: application/json' \
  -H 'Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJodHb2JzLmNvbSIsImV4cCEHad6bFVnvAQJElIY' \
  -H 'Content-Type: application/json' \

  -d '{
"country": "US",
"searchType": "semantic",
"semantic": {
"jobTitles": [
"Software Engineer"
],
"skills": [
{
"name": "Java",
"importance": "Required"
}
],
"locations": [
{
"city": "Boston",
"state": "MA",
"country": "US"
}
]
}
}'

The example request will yield "page 1", containing 10 candidates.

The HTTP response headers contains a Link header that contains URLs to call to get the "first, prev, next and last" pages for the data set: 

Link: <https://api.jobs.com/v2/candidates/queries?page=1&perPage=10>; rel="first",<https://api.jobs.com/v2/candidates/queries?page=1&perPage=10>; rel="prev",<https://api.jobs.com/v2/candidates/queries?page=2&perPage=10>; rel="next",<https://api.jobs.com/v2/candidates/queries?page=75&perPage=10>; rel="last"

 

 

country (string, HIGHLY RECOMMENDED):

A single country abbreviation. E.g. US, UK, CA. Omitting country will search all countries and may have undesired results. The country parameter determines context and search behavior in two ways.

1.       Sets the Monster site for your search. Monster users may login on any of our global sites. The country parameter limits the search to users that have created their profiles on these sites.

·         US – Monster.com

·         CA – Monster.ca

·         UK – Monster.co.uk

2.       Sets the context for location searching. Monster’s geolocation provides a very flexible method for resolving locations. The country parameter selects the geolocation database for search. This resolves ambiguous locations based on country. For example:

·         With country = CA, London = London, Ontario, Canada

·         With country = UK, London = London, England

·         With country = US, London = London, Kentucky, USA

resumeBoardId (integer):

The resume board id 1 is the Monster Public Board. 

searchType (string):

Defines if the user is providing parameters for the semantic search engine or matching with a job description/id. Possible values:

·         "JobDetail". Automated matching using Monster AI to construct a search based on a job title, job description and location.

·         "Semantic". Full function semantic search and hybrid semantic/Boolean search.

 

The basic parameters used for most semantic searches include Titles, Skills and Location.

jobTitles (Array[string]):

A comma separated list of Job Titles to search.

skills (Array [Skill]): 

List of all skills to be searched with an optional importance.

name (string):

The skill name

importance (string):

Possible values:

·         "Required"

·         "NiceToHave" (default)

locations (Array [Location]):

List of all locations to be included in search, composed of the city, state, postal code, and radius. It's also possible to provide a location expression.

city (string):

City name of the location. E.g. "New York City", "Boston", etc.

state (string):

The state abbrev of the location. E.g. "NY", "CA", etc.

postalCode (string):

Postal code of the location. E.g. "0186".

radius (integer):

Radius of this location search (considering the radius unit), default 25 miles.

radiusUnit (string):

Radius Unit of this location search. Allowed values (case insensitive):

For Miles (default):  §  "Miles"  §  "Mi"  §  "M"

For Kilometers: §  "Kilometers" §  "Kilometres" (international standard) §  "Km" §  "K"

locationExpression (string):

NOTE: This field is cannot be used in combination with the other location fields. The encoded location expression may contain the city, state, postal code or other location description (ex Los Angeles County, CA). Multiple expressions are comma separated. Radius may be included in the expression or radius may be used.
 

yearsOfExperience (YearsOfExperience)

expression (string, optional):
Expression to describe the number of years’ experience for the search. Calculated from date ranges in the work history section of the resume. Accepted format:

§  Single number of years (Ex.: "1"); or
§  Range of years (Ex.: "1-5" inclusive); or
§  Greater than expression (Ex.: “>5”); or
§  Greater than expression (Ex.: "5+" encoded as "5%2b"); or
§  Less than expression (Ex.: "<3", "<8").
  importance (string, optional):
 
  Possible values:
§  "Required"
§  "NiceToHave" (default)

schools (Array[string]):

A comma separated list of schools. (ex. “Harvard”, “Yale”, “UCLA”)

degrees (Array [Degree]):

A comma separated list of degrees with optional importance. (ex. “MBA”, “Computer Science”)

degreeName (string):
Name of the degree.
importance (string):

Possible values:

§  "Required"
§  "NiceToHave" (default)

companies (Array [string]):

A comma separated list of companies. (ex. “Lockheed”, “Raytheon”, “Northrup Grumman”)

jobTenure (number):

Average tenure for all jobs on a resume, specified in fractions of a year.

E.g. 0.5 (means 6 months). 1 (means 1 year)

lastActiveMaximumAge (integer):

Maximum time since the seeker was active on Monster (in minutes). Does not apply to private resume databases.

resumeUpdatedMaximumAge (integer):

Maximum time since resume was updated (in minutes).

resumeUpdatedMinimumAge (integer):

Minimum time since resume was updated (in minutes).



Job Detail provides automated matching to analyze a job title and job description and generate an effective semantic search based on critical skill found in the job description. In general, JobDetail works with a jobTitle, jobDescription and location. For nationwide searches, the location can be omitted.

jobTitle (string):

Title of the job. Multiple titles may be separated commas.

jobDescription (string):

Full text of the Job Description. The text may contain HTML. Special characters need to be escaped to comply with standard JSON encoding.

locations (Array [Location]):

List of all locations to be included in search, composed of the location name, state, postal code, country and radius. It's also possible to provide a location expression.

city (string):

City name of the location. E.g. "New York City", "Boston", etc.

state (string):

The state abbrev of the location. E.g. "NY", "CA", etc.

postalCode (string):

Postal code of the location. E.g. "90210".

radius (integer):

Radius of this location search (considering the radius unit), default 25 miles.

radiusUnit (string):

Radius Unit of this location search. Allowed values (case insensitive):

For Miles (default):
· "Miles"
· "Mi"
· "M"

For Kilometers:

· "Kilometers"
· "Kilometres" (international standard)
· "Km"
· "K"

locationExpression (string, optional):

NOTE: This field is cannot be used in combination with the other fields. The encoded location expression may contain the city, state, postal code or other location description (ex: Los Angeles County, CA). Multiple expressions are comma separated. Radius may be included in the expression or radius may be used.

jobId (string):

An optional method for identifying a job based on the Monster posting ID. The string is a formatted GUID.

jobDescriptionBase64 (string):

Optionally, the job description can be provided as a Base64 encoded string.

 

These parameters are useful when building/debugging your integration:

resumeValues (Array [string]):

List of resume values. This provides direct search for an individual resumes. 

candidateName (string):

Name of a single candidate to look for.

 

 

FOR LIMITED USE CASES. PLEASE BE CAREFUL and ONLY USE FOR SPECIFIC CASES. The allows for searching by resume-based semantic fields, profile fields and boolean WHERE ONLY THE UNION OF RESULTS WILL BE RETURNED.

Boolean search are not contextual. The search strings may occur anywhere on the resume. These search techniques are less effective than semantic and should be considered for non-semantic keywords or for exclusion of terms (logical NOT).

Boolean results are unranked.

 

booleanExpression (BooleanExpression):

The Boolean Keyword expression to use in the search. Logical operators include AND, OR, NOT, wildcards “*” and multi-word strings “Accounting Clerk”. Terms may be grouped using parentheses.

expression (string,):

The Boolean Expression, written in Monster Query Syntax. E.g. "java AND (\"web services\" OR xml) AND program*".

importance (string, optional):

The importance of this Boolean expression (to guide the search engine ratings). Possible values are             
§ 
"Required"
§  "NiceToHave


EXAMPLE:

{
  "searchType": "semantic",
  "country": "US",
  "semantic": {
      "jobTitles": [
        "Sales Manager",
       ],
      "booleanExpression": {
          "expression": "NOT retail",
          "importance": "required",
        },
    },
}


This lets you look up full details a candidate by its identifier (textResumeID and Board ID together).
Retrieval calls made against Monster boards will incur an inventory charge.

Retrieving a resume, every time it is retrieved, will decrement the resume view inventory. With API resume retrievals Monster does not track whether a resume has previously been downloaded. Tracking needs to be done on client side to to avoid unwanted inventory usage.

 

Root URL

The root URL is GET: https://api.jobs.com/v2/candidates/

 

Query Parameters

Parameter

Type

Description

Default

textResumeId

string

Text resume ID of the candidate. This ID is found in the search response

1

resumeBoardId

integer

The ID of the Board to get the candidate from.

1

verbose

boolean

If true it will include the text resume and the actual resume document in the response, in base 64 format

false

 

Example Request for full candidate details

curl -X GET \

  'https://api.jobs.com/v2/candidates/dtprdakru7rw8b2u?resumeBoardId=1&verbose=true' \

  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjBhOVZOQ0RmNFkJi-CN2tw9Y-QyDoZMKRV1_ZQk6M1RrWjrCm653Vm8YNeiSWwT_A'



Search Request Sample:

{
"country": "US",
"searchType": "semantic",
"semantic": {
"jobTitles": [
"Desktop Support Specialist"
],
"resumeUpdatedMaximumAge": 14400,
"skills": [
{
"name": "Desktop Support",
"importance": "Required"
},
{
"name": "Software Development",
"importance": "NiceToHave"
}
],
"degrees": [
{
"degreeName": "Software Engineering",
"importance": "NiceToHave"
}
],
"locations": [
{
"city": "Orange",
"state": "CA",
"radius": 40
}
]
}
}

Search Response Schema

The response is encoded in JSON and is quite detailed. 

Note: with verbose mode, the originalCriteria and searchCriteria are included in the response. The schema for these can be referenced above

{

"originalCriteria": {}
 
"searchCriteria": {}
 

 "boards": [
{

"id": 0,

"name": "string",
 
"matched": 0
 
}
 
],
 
"candidates": [
 
{
 
"identity": {
 
"seekerRefCode": "string",
 
"textResumeID": "string",
 
"resumeModifiedDate": "2018-12-14T17:12:12.730Z",
 
"md5EmailAddress": "string",
 
"name": "string"
 
},
 
"location": {
 
"city": "string",
 
"state": "string",
 
"postalCode": "string",
 "country": "string", 
"willRelocate": true, 
"workAuthorizations": [
 
{
 
"authorization": "string",
 
"country": "string"
 
}
 
]
 
},
 
"degree": "string",
 
"yearsOfExperience": 0,
 
"relevance": {
 
"score": 0,
 
"experience": {
 
"title": {
 
"name": "string",
 
"matched": "string"
 
},
 
"company": {
 
"name": "string",
 
"matched": "string"
 
},
 
"start": "2018-12-14T17:12:12.730Z",
 
"end": "2018-12-14T17:12:12.730Z"
 
},
 
"skills": [
 
{
 
"name": "string",
 
"yearsOfExperience": 0,
 
"lastUsed": "2018-12-14T17:12:12.730Z",
 
"matched": "string"
 
}
 
]
 
},
 
"veteran": true,
 
"viewed": true,
 
"lastActive": "2022-10-14T17:12:12.730Z",
 
"boards": [
 
{
 
"id": 1,
 
"name": "string"
 }

 ] } ]  } 

Candidate Detail Schema

{
"identity": {
"seekerRefCode": "string",
"textResumeID": "string",
"resumeModifiedDate": "2018-12-14T17:12:12.833Z",
"md5EmailAddress": "string",
"emailAddress": "string",
"name": "string"
}, 
"location": { 
"city": "string", 
"state": "string", 
"postalCode": "string", 
"country": "string", 
"willRelocate": true, 
"workAuthorizations": [ 

"authorization": "string", 
"country": "string" 
} ] }, 
"yearsOfExperience": 0, 
"relevance": { 
"score": 0, 
"experience": { 
"title": { 
"name": "string", 
"matched": "string" 
}, 
"company": { 
"name": "string", 
"matched": "string" 
}, 
"start": "2022-10-14T17:12:12.834Z", 
"end": "2022-10-15T17:12:12.834Z" 
}, 
"skills": [ 

"name": "string", 
"yearsOfExperience": 0, 
"lastUsed": "2022-10-14T17:12:12.834Z", 
"matched": "string" 
} ] }, 
"veteran": true, 
"viewed": true, 
"lastActive": "2018-12-14T17:12:12.834Z", 
"boards": [ { 
"id": 0, 
"name": "string" 
} ], 
"resumeTitle": "string", 
"securityClearance": { 
"country": "string", 
"clearance": "string" 
}, 
"source": "string", 
"targetJobTitle": "string", 
"desiredSalary": { 
"min": "string", 
"max": "string", 
"period": "string", 
"currency": "string" 
}, 
"phoneNumbers": [ 

"phoneNumberValue": "string", 
"priority": "string", 
"type": "string" 
} ], 
"willTravel": true, 
"highestEducationDegree": "string", 
"educationalHistory": [ 

"schoolName": "string", 
"degree": "string", 
"majors": [ 
"string" 
], 
"start": "2018-12-14T17:12:12.834Z", 
"end": "2018-12-14T17:12:12.834Z" 

], 
"externalRequisitions": [ 
"string" 
], 
"resumeModifiedDate": "2022-10-14T17:12:12.834Z", 
"resume": "string", 
"resumeDocument": {
  "fileName": "string",
  "fileContentType": "string",
  "file": "string"
}