Candidate Search API
The following information is for resume search and retrieval integration. It describes the authentication method, the search and the retrieval how to 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, quality of education, relevant skills and location, and matches these against the job requirements.
The result: within seconds, the very best candidates for each unique position are presented, in rank order, and in a standardized view. This saves the recruiter’s and hiring manager’s time, expedites the hiring process, improves the quality of your hires, reduces recruiting cost, and streamlines the overall process.
6Sense intelligent search provides you with a powerful semantic search engine, which will give you access to real time “intelligent” search capabilities to find qualified candidates from Monster or your private resume database. 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 – Using Monster’s Artificial Intelligence eliminates the need for a recruiter to conduct a search. Monster’s AI technology analyzes a job title and description to construct and execute a search based on critical skills found in the job description.
Authentication
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.
Calling the Search API
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 Request - showing paging parameters
curl -X POST \
'https://api.jobs.com/v2/candidates/queries?page=2&perPage=3' \
-H 'Accept: application/json' \
-H 'Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJodHb2JzLmNvbSIsImV4cCEHad6bFVnvAQJElIY' \
-H 'Content-Type: application/json' \
-d '{
"searchType": "jobDetail",
"jobDetail": {
"jobTitle": "Java Programmer",
"jobDescription": "Java XML Spring",
"locations": [
{
"city": "Waltham",
"state": "MA",
"country": "US"
}
]
}
}'
The example request will yield "page 2", containing 3 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 HTTP response headers
Link: <https://api.jobs.com/v2/candidates/queries?page=1&perPage=3>; rel="first",<https://api.jobs.com/v2/candidates/queries?page=1&perPage=3>; rel="prev",<https://api.jobs.com/v2/candidates/queries?page=3&perPage=3>; rel="next",<https://api.jobs.com/v2/candidates/queries?page=226&perPage=3>; rel="last"
Base Parameters
The request body is written in JSON and is quite detailed. The following parameters determine basic functionality and context.
Here is a simple search body example:
"searchType": "semantic",
"semantic": {
"jobTitles": [
"Desktop Engineer"
],
"locations":[
{ "city": "Weston",
"state": "MA",
"postalcode": "02493",
"radius": "30"
}
],
"skills": [
{
"name": "Firewalls",
"importance": "Required" }
]
}
}
country (string, optional HOWEVER 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, optional):
The resume board against which candidates will be matched. For every country the Monster Public Board is number 1. For private boards, Monster will provide the resumeBoardId.
searchType (string, optional):
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.
JobDetail
Job Detail provides automated matching using Monster Artificial Intelligence 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, optional):
Title of the job. Multiple titles may be separated commas.
jobDescription (string, optional):
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], optional):
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, optional):
City name of the location. E.g. "New York City", "Boston", etc.
state (string, optional):
The state abbrev of the location. E.g. "NY", "CA", etc.
postalCode (string, optional):
Postal code of the location. E.g. "90210".
radius (integer, optional):
Radius of this location search (considering the radius unit), default 25 miles.
radiusUnit (string, optional):
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, optional):
An optional method for identifying a job based on the Monster posting ID. The string is a formatted GUID.
jobDescriptionBase64 (string, optional):
Optionally, the job description can be provided as a Base64 encoded string.
Semantic
Semantic search provides full functionality for search using resume-based semantic concepts, candidate profile information and hybrid semantic/keyword.
Basic Search Parameters
The basic parameters used for most semantic searches include Titles, Skills and Location.
jobTitles (Array[string], optional):
A comma separated list of Job Titles to search.
skills (Array [Skill], optional):
List of all skills to be searched with an optional importance.
name (string, optional):
The skill name
importance (string, optional):
Possible values:
· "Required"
· "NiceToHave" (default)
locations (Array [Location], optional):
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, optional):
City name of the location. E.g. "New York City", "Boston", etc.
state (string, optional):
The state abbrev of the location. E.g. "NY", "CA", etc.
postalCode (string, optional):
Postal code of the location. E.g. "0186".
radius (integer, optional):
Radius of this location search (considering the radius unit), default 25 miles.
radiusUnit (string, optional):
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 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, optional)
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], optional):
A comma separated list of schools. (ex. “Harvard”, “Yale”, “UCLA”)
degrees (Array [Degree], optional):
A comma separated list of degrees with optional importance. (ex. “MBA”, “Computer Science”)
degreeName (string, optional):
Name of the degree.
importance (string, optional):
Possible values:
§ "Required"
§ "NiceToHave" (default)
companies (Array [string], optional):
A comma separated list of companies. (ex. “Lockheed”, “Raytheon”, “Northrup Grumman”)
jobTenure (number, optional):
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, optional):
Maximum time since the seeker was active on Monster (in minutes). Does not apply to private resume databases.
resumeUpdatedMaximumAge (integer, optional):
Maximum time since resume was updated (in minutes).
resumeUpdatedMinimumAge (integer, optional):
Minimum time since resume was updated (in minutes).
Monster provides users with a robust profile including information not found on a resume. CAREFUL!! Users are NOT REQUIRED to complete their profile. Consequently, using these fields for search may NOT return all the expected candidates.
resumeValues (Array [string], optional):
List of resume values. This provides direct search for an individual, unique resume.
minEducationLevel (string, optional):
Single education level by which to be filtered. This field is reasonably well populated by Monster users. Possible values are:
· "HighSchoolOrEquivalent"
· "Certification"
· "Vocational"
· "AssociateDegree"
· "BachelorsDegree"
· "MastersDegree"
· "Doctorate"
· "Professional"
· "SomeCollegeCourseworkCompleted"
· "SomeHighSchoolCoursework"
willingnessToRelocate (boolean, optional):
Flag indicating the candidate's willingness to relocate.
willingnessToTravel (string, optional):
Willingness to travel. Possible values:
· "NoTravelRequired"
· "UpTo25PercentTravel"
· "UpTo50PercentTravel"
· "UpTo75PercentTravel"
· "OneHundredPercentTravel"
candidateName (string, optional):
Name of a single candidate to look for.
careerLevels (Array[string], optional):
List of career levels to be filtered. Possible values are:
· "President"
· "ExecutiveLevel"
· "GeneralManager"
· "VicePresident"
· "Director"
· "Head"
· "Manager"
· "Lead"
· "Other"
· "Analyst"
· "Representative"
· "Specialist"
· "Clerk"
· "Coordinator"
· "Assistant"
jobTypes (Array [string], optional):
List of target job types by which to be filtered. Possible values are:
· "WantsPermanent"
· "WantsContract"
· "WantsIntern"
· "WantsTemp"
· "WantsSeasonal"
veteranCandidates (boolean, optional):
Flag to indicate whether to look only for (military) veteran candidates.
securityClearances (Array [SecurityClearance], optional):
US only. List of all security clearances (composed of country id and clearance id). Reference clearance ID at https://integrations.monster.com/Toolkit/Enumeration/ClearanceLevel
countryAbbrev (string, optional):
A single country abbreviation. E.g. FR, US, CZ, BR
clearanceId (integer, optional):
Clearance id.
languageProficiencyLevels (Array [LanguageProficiencyLevel], optional):
List of all language proficiency levels.
languageCode (string, optional):
Language code accordingly the ISO standards. E.g. "en" (English), "fr" (French).
proficiency (string, optional):
Holds the proficiency name for the given language. Possible values:
§ "Unknown"
§ "Beginner"
§ "Intermediate"
§ "Advanced"
§ "Fluent"
salary (Salary, optional):
Candidate self-identified target salary related properties. This profile information is seldom provided and should not be considered as actual or current salary.
minimum (integer, optional):
Minimum Salary.
maximum (integer, optional):
Maximum Salary.
currencyAbbrev (string, optional):
Currency Abbreviation. E.g. USD, BRL, CZK, etc...
includeResumesWithoutSalary (boolean, optional):
Indicates if results without salary should be included.
workAuthorizations (Array [WorkAuthorization], optional):
List of work authorizations by country.
countryAbbrev (string, optional):
A single country abbreviation. E.g. FR, US, CZ, BR.
workStatus (string, optional):
Current work status. Possible values:
§ "AuthorizedToWorkForAnyEmployer"
§ "AuthorizedToWorkForPresentEmployer"
§ "RequireSponsorship"
legalStatuses(Array[LegalStatus], optional):
List of all legal statuses composed of the country abbreviation and the legal status name.
countryAbbrev (string, optional):
A single country abbreviation. E.g. FR, US, CZ, BR.
legalStatusName (string, optional):
Legal status name. Possible values are:
§ "Citizen"
§ "PermanentResident"
§ "Other"
Monster provides a hybrid semantic/keyword search capability 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 keyword/Boolean WHERE ONLY THE UNION OF RESULTS WILL BE RETURNED. Keyword and 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/Keyword results are unranked.
keywords (Array[string], optional):
List of Keywords to consider in the search. All keywords must be present (logical AND). Ex.: “Software Engineer”, DevOps
booleanExpression (BooleanExpression, optional):
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, optional):
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"
The following search parameters are ONLY APPLICABLE to private resume databases that must be purchased by clients.
channelId (integer, optional):
Monster provided Channel ID for the search.
seekerRefCodes (Array[string], optional):
List of seeker RefCodes. This usually is the Candidate ID from the Applicant Tracking System (ATS) as provided in the resume upload integration.
requisitionCodes (Array[string], optional):
List of requisition codes. This usually refers to Job ID’s in the ATS the seeker has applied to. On occasion this field is used as a semi-custom field for other information. Populated by the resume feed.
resumeSourceIds (Array[integer], optional):
List of resume source IDs. Reference: https://integrations.monster.com/Toolkit/Enumeration/ResumeOrigin
customField (CustomField, optional):
A preconfigured Monster custom field (containing its id and list of integer values). Private resume databases have a limited custom field capability. These custom fields are configured by Monster and populated by the resume feed from the ATS to the private resume database.
id (integer, optional):
Custom Field ID
values (Array [integer], optional):
Values associated with this custom field.
Retrieving Candidate Details and Resumes
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. Monster does not track whether a resume has previously been downloaded, so client needs to track that to avoid using up inventory.
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 Schema
{
"country": "string","searchType": "string",
"resumeBoardId": 0,
"jobDetail": {
"jobId": "00000000-0000-0000-0000-000000000000",
"jobTitle": "string",
"jobDescription": "string",
"jobDescriptionBase64": "string",
"locations": [
{
"city": "string",
"state": "string",
"postalCode": "string",
"radius": 0,
"radiusUnit": "string",
"locationExpression": "string"
} ],
},
"semantic": {
"booleanExpression": {
"expression": "string",
"importance": "string"
},
"candidateName": "string",
"careerLevels": [
"string"
],
"channelId": 0,
"companies": [
"string"
],
"customField": {
"id": 0,
"values": [
0
]
},
"degrees": [
{
"degreeName": "string",
"importance": "string"
}
],
"jobTenure": 0,
"jobTitles": [
"string"
],
"jobTypes": [
"string"
],
"keywords": [
"string"
],
"languageProficiencyLevels": [
{
"languageCode": "string",
"proficiency": "string"
}
],
"legalStatuses": [
{
"legalStatusName": "string",
"countryAbbrev": "string"
}
],
"locations": [
{
"city": "string",
"state": "string",
"postalCode": "string",
"radius": 0,
"radiusUnit": "string",
"locationExpression": "string"
}
],
"minEducationLevel": "string",
"requisitionCodes": [
"string"
],
"resumeSourceIds": [
0
],
"lastActiveMaximumAge": 0,
"resumeUpdatedMaximumAge": 0,
"resumeUpdatedMinimumAge": 0,
"resumeValues": [
"string"
],
"salary": {
"minimum": 0,
"maximum": 0,
"currencyAbbrev": "string",
"includeResumesWithoutSalary": true
},
"schools": [
"string"
],
"skills": [
{
"name": "string",
"importance": "string"
}
],
"securityClearances": [
{
"clearanceId": 0,
"countryAbbrev": "string"
}
],
"seekerRefCodes": [
"string"
],
"veteranCandidates": true,
"willingnessToRelocate": true,
"willingnessToTravel": "string",
"workAuthorizations": [
{
"workStatus": "string",
"countryAbbrev": "string"
}
],
"yearsOfExperience": {
"expression": "string",
"importance": "string"
}
} }
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"
}