Job Search API

Authentication and Authorization

Input Parameters

Response Format

Job Search API Version 2

 

This document describes the Monster Job Search API Version 2. See this guide for documentation on previous version. 


Summary

Monster Job Search V2 is exposed to the programmer through a simple HTTP interface. Query parameters are sent via a single HTTP GET or POST query and search results, errors and diagnostic information are returned as an XML or JSON document based on standard HTTP content negotiation through headers. This version of the Job Search API has consistent use of all lowercase on the parameters and properties.

URL:
https://api.jobs.com/v2/search/jobs

Examples

External example:
https://api.jobs.com/v2/search/jobs?title=programmer&city=boston&state=MA&radius=40&country=US

 

Authentication and Authorization

Authentication and authorization happens through standard Reverse Proxy means.

First you need to authentication by supplying your AppID and AppSecret:
- POST
https://api.jobs.com/auth/token?AppId=MyApp&AppSecret=abcdaxkld1235

In case the supplied authentication information is valid, Reverse Proxy will respond with following information 

{ "Token": "eyJ0kld…", "Expires": "2015-02-14T02:34:15.0813256Z" }


The JWT token supplied in the response is then used for all subsequent requests by the application until it expires. Once it expires, new JWT has to be obtained by re-authenticating.

In the subsequent requests, the JWT token is supplied in the Authorization HTTP header

Authorization: bearer eyJ0kld…

 

Input Parameters

Parameter Format

All input parameters must be sent using HTTP GET. Care should be taken to URL-encode all parameters correctly. Malformed parameters will either be incorrectly interpreted and or give rise to unexpected results, or a 0xA0002000 – Invalid Input Parameter error will be returned.

Parameters listed as "multi-valued" accept multiple values and may be entered by repeating the parameter as shown in the examples that follow each parameter description.

All parameters are case insensitive.

Query Parameters

Name Description Example Required Default
country Country of the jobs, see Abbreviations country=US Yes N/A
state State of the jobs state=MA No None
city City of the jobs city=Boston No None
radius Radius around the location to get the jobs for (in miles) radius=45 No 25 miles
title Title of the jobs title=plumber No None
company Company of the jobs company=Monster No None
age How old jobs (at maximum) should be included in the result age=30 No None (does not filter jobs by age)
mesco Mesco of the jobs mesco=1003252001 No None
skills Skills of the job skills=java No None
orderby Type of sorting orderby=latest No None
companyguid Company KB Guid of the jobs companyguid=ab2323-a3242435-dds No None
boardids Boards to limit the jobs to. boardIds=1-2-3 No None
keywords Any keywords to refine the search keywords=java No None
jobtype Type of Jobs (PartTime,Contract,Temp,Internship,Other,FullTime,WorkAtHome) jobtype=fulltime-contract No None
companyxcode xcode of the Company that Monster provides companyxcode=xclientnamex No None



Supported Fields with Examples

/api/v2/jobsearch/?country=US&keywords=software
/api/v2/jobsearch/?country=US&keywords=software&orderby=latest
/api/v2/jobsearch/?country=US&title=Software%20Engineer
/api/v2/jobsearch/?country=US&title=Software%20Engineer
/api/v2/jobsearch/?country=US&company=IBM
/api/v2/jobsearch/?country=US&mesco=1300087001001
/api/v2/jobsearch/?country=US&boardids=7086
/api/v2/jobsearch/?country=US&companyxcode=xfredx
/api/v2/jobsearch/?country=US&skills=software
/api/v2/jobsearch/?country=US&city=Waltham
/api/v2/jobsearch/?country=US&state=MA
/api/v2/jobsearch/?country=US&state=MA&City=Waltham&radius=20
/api/v2/jobsearch/?country=US&jobtype=parttime&jobtype=fulltime
/api/v2/jobsearch/?country=US&postalcode=02401
/api/v2/jobsearch/?country=US&state=MA&City=Waltham&radius=20&radiusUnit=kilometers
/api/v2/jobsearch/?country=US&state=MA&City=Waltham&radius=20&radiusUnit=miles
/api/v2/jobsearch/?country=US&state=MA&City=Waltham&radius=20&radiusUnit=foo
/api/v2/jobsearch/?country=US&state=MA&Age=1
/api/v2/jobsearch/?country=US&state=MA&Age=30
/api/v2/jobsearch/?country=US&jobtype=other
/api/v2/jobsearch/?country=US&careerlevel=Executive


Controlling the Results

The maximum number of jobs returned is limited to 1000 to not impact performance of the search engines. Attempting to specify a combination of values that would result in returning the 1001th job or higher will not return those jobs.

Paging (Link Style)
The page and perpage parameter indicates controls the result set that is going to be returned 

Examples:

	page=1&perpage=100		return 20 results starting with the 1st job


The default page is 1, the default per page is 20.

In standard RESTful way, the response will also contain link style 

Link:
<https://api.jobs.com/v2/search/jobs?title=Engineer&page=1&perpage=100>; rel="first",
<https://api.jobs.com/v2/search/jobs?title=Engineer&page=1&perpage=100>; rel="prev",
<https://api.jobs.com/v2/search/jobs?title=Engineer&page=3&perpage=100>; rel="next",
<https://api.jobs.com/v2/search/jobs?title=Engineer&page=12&perpage=100>; rel="last"


Total Hits

The total number of available jobs (total hits) is available in the response as a header with name "TotalHits" and value of the number of the total number of hits for that given search terms.

Date format

Dates in query results are formatted according to the ISO 8601 standard.

Times are expressed in local time, together with a time zone offset in hours and minutes. For example: 2005-03-04T20:22:25-05:00.

 

Response Format

Field Description Example
city city where job is located city="Brockton"
state state abbreviation where job is located state="MA"
postalcode postalcode where job is located postalcode="02401"
refcode unique identifier from provider of job refcode=12039348
datecreated date the job was created datecreated=7/4/2018 6:02:27 AM
companyguid guid to identify company companyguid=b2162f9b-b4c5-4fb0-92b8-b496168b4567
companyname name of company companyname=Acme
title title of job title="Software Engineer"
url url of job url=https://www.testcompany.com/test
summary partial summary of job summary="Looking for a candidate for software engineer"
postingid unique id of job postingid=456ac77b-b487-476d-906a-60bdc35590b3
mesco monster category for job "mesco":{"id":1500127001001}

 

Media Type

Both JSON and XML are support. Use the standard HTTP content negotiation to ensure you receive proper format (i.e. Accept header).

JSON

[
  {
    "location": "Alpharetta, GA, 30004",
    "distance": "-1,NaN,INVALID_QUERY_LOCATION",
    "refCode": "d2253c82-93f4-4ee3-bf8d-2eda1d2db0a8",
    "dateCreated": "06\/02\/2016 12:00:00 AM",
    "companyName": "Solutions Inc.",
    "title": "not solution abstract best nervous",
    "url": "https:\/\/jobview.monster.com\/GetJob.aspx?JobID=3982983",
    "summary": "not solution abstract best nervous premium industrial requesting vaste fact master valuable historical letter vaste requirement brainstorming create similar create oposite extra letter fantastic a no newest sampling problems win human sing violin a ...",
    "postingId": "d73d0459-11c5-423a-9578-77bb0a3f28a6",
    "id": "1837271",
    "score": 93.448,
    "companyGuid": "sdfsa74example5sdfkjhdsg",
    "mesco": {
      "id": 4100672001001,
      "alias": "Advertising Sales Agents"
    }
  },
  {
    "location": "Alpharetta, GA, 30009",
    "distance": "-1,NaN,INVALID_QUERY_LOCATION",
    "refCode": "8b9e0f24-430a-4ea3-a10a-65020088c799",
    "dateCreated": "06\/02\/2016 12:00:00 AM",
    "companyName": "Violins Inc.",
    "title": "scale sample violin features features",
    "url": "https:\/\/jobview.monster.com\/GetJob.aspx?JobID=3909161",
    "summary": "scale sample violin features features filtering public business total newest almanah statuses freezing rest and stateman are better Cambridge cooking between statuses abstract Cambridge craftman problematic almanah united crucial info creative never...",
    "postingId": "d216f96d-bea5-4a8d-ae7c-23e81791f564",
    "id": "1831568",
    "score": 93.448,
    "companyGuid": "sdfs345345example2hdsg65757",
    "mesco": {
      "id": 1300093001001,
      "alias": "Business Operations Specialists, All Other"
    }
  }
]


XML

<jobs>
  <job>
    <Location>Alpharetta, GA, 30004</Location>
    <Distance>-1,NaN,INVALID_QUERY_LOCATION</Distance>
    <RefCode>d2253c82-93f4-4ee3-bf8d-2eda1d2db0a8</RefCode>
    <DateCreated>06/02/2016 12:00:00 AM</DateCreated>
    <CompanyName>Solution Company</CompanyName>
    <Title>not solution abstract best nervous</Title>
    <Url>https://jobview.monster.com/GetJob.aspx?JobID=3982983</Url>
    <Summary>not solution abstract best nervous premium industrial requesting vaste fact master valuable historical letter vaste requirement brainstorming create similar create oposite extra letter fantastic a no newest sampling problems win human sing violin a ...</Summary>
    <PostingId>d73d0459-11c5-423a-9578-77bb0a3f28a6</PostingId>
    <Id>1837271</Id>
    <Score>93.448</Score>
    <CompanyGuid>sdf23s1example1sdfkjhdsg</CompanyGuid>
    <Mesco>
        <Id>4100672001001</Id>
        <Alias>Advertising Sales Agents</Alias>
    </Mesco>
  </job>
  <job>
    <Location>Alpharetta, GA, 30009</Location>
    <Distance>-1,NaN,INVALID_QUERY_LOCATION</Distance>
    <RefCode>8b9e0f24-430a-4ea3-a10a-65020088c799</RefCode>
    <DateCreated>06/02/2016 12:00:00 AM</DateCreated>
    <CompanyName>Violin Company</CompanyName>
    <Title>scale sample violin features features</Title>
    <Url>https://jobview.monster.com/GetJob.aspx?JobID=3909161</Url>
    <Summary>scale sample violin features features filtering public business total newest almanah statuses freezing rest and stateman are better Cambridge cooking between statuses abstract Cambridge craftman problematic almanah united crucial info creative never...</Summary>
    <PostingId>d216f96d-bea5-4a8d-ae7c-23e81791f564</PostingId>
    <Id>1831568</Id>
    <Score>93.448</Score>
    <CompanyGuid>sdf923s2example2sdfkjhdsg</CompanyGuid>
    <Mesco>
        <Id>1300093001001</Id>
        <Alias>Business Operations Specialists, All Other</Alias>
    </Mesco>   
  </job>
  <job>
    <Location>Alpharetta, GA, 30009</Location>
    <Distance>-1,NaN,INVALID_QUERY_LOCATION</Distance>
    <RefCode>91b48cad-0e4a-43fc-a024-44f2eb7e42c4</RefCode>
    <DateCreated>06/02/2016 12:00:00 AM</DateCreated>
    <CompanyName>Database Company</CompanyName>
    <Title>scale database best brainstorm historic</Title>
    <Url>https://jobview.monster.com/GetJob.aspx?JobID=3908436</Url>
    <Summary>scale database best brainstorm historic watter put not water eco find use ground humble sing logical creating humour afternoon sing flodding usage coding center factual logical catamaran talent master designer flood infrastructure win newer quickly ...</Summary>
    <PostingId>b0acd05d-30a4-4247-9fa2-c4f3841d9839</PostingId>
    <Id>1831434</Id>
    <Score>93.448</Score>
    <CompanyGuid>sdf923s2example375ykjh39867dsg</CompanyGuid>
    <Mesco>
        <Id>1300093001001</Id>
        <Alias>Business Operations Specialists, All Other</Alias>
    </Mesco>    
  </job>
</jobs>

Getting the Full Job Details


Uses the PostingId from the jobsearch results and call the following:

https://api.jobs.com/jobs/b0acd05d-30a4-4247-9fa2-c4f3841d9839




Error Results

All errors are returned in an Errors node thus:

In JSON:

{"status":"error","error":"countryId 0 not supported in Powersearch or Medley index"}

In XML:
<result xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
    <error>countryId 0 not supported in Powersearch or Medley index</error>
    <status>error</status>
</result>