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.
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. | 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/
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": {}
{
"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"
}