Easy Apply Integration Guide

The following is information about delivery part of the Easy Apply integration. It describes the formats and the how to steps. 

How do I start this integration?

Please read this developer guide and contact platformpartners@monster.com or your Monster Representative to obtain your Easy Apply API key.

What data formats are supported?

Monster apply supports both JSON and XML data format for the applicant records.  

What fields are provided in the Monster Apply?

The applicant data record is comprised of the following fields. Some are optional so they are only populated if the seeker or the job posting supplied the information.
Field Type Notes
integratedApplyID UUID Integrated Apply Entity Identifier.
sourceAttribution String Optional String field, specifying source of the apply, e.g. Monster, MIL, MSTS. Applies from jobs posted on Monster will have "monster" for this value.
applicant Object The applicant field encapsulates all information related to the job applicant. (Name, address, contact details, workAuthorization, etc.) See below for Applicant Object.
jobRefCode String This is the jobrefcode sent in on a job posted to Monster. It is the customer's identification for the job.
vendorText String This is the text value optionally provided in the VendorText sent in on the job posted to Monster.
questions Object This is the list containing Q&A objects (Questionnaire Response) as part of the job apply. See below for Question Object.

Applicant Object
Field Type Notes
city String  
countryCode String This is the 2 letter ISO value for the country.
emailAddress String  
firstName String  
lastName String  
phoneNumber String  
region String  
resume Object The resume field contains information related to the candidate’s resume. See below for Resume Object.
workAuthorization String This is a value of whether the applicant is authorized to work in the country provided in the countryCode.
postalCode String  



Resume Object
Field Type Notes
fileName String The full resume file name.
fileContents String Resume document file contents - Base64 encoded string representation of the byte array to unify the representation. (JSON and XML format) This resume document is derived either from user-uploaded documents or a rendered resume based on the applicant profile. If the resume was created interactively on Monster, the resume is provided as a PDF. If an applicant originally uploaded a resume to Monster (e.g., as a DOCX, PDF), it is delivered in the original document format. Resume size can be up to 5 MB. Due to some additional data and overhead coming from the serialization / deserialization process, XML format should be set to accept larger size payloads.
contentType String The content-type that is derived from the response header when retrieving the rendered resumes or user-uploaded documents. Example values: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document




Question Object
Field Type Notes
questionKey String The Unique identifier of the question in the context of a single questionnaire. This key is supplied by the partner to aid mapping questions to the partner's internal ATS model.
text String A textual representation of the question.
answer List<String> A list of String-type value(s) that contains the applicant’s answer to the question.



Delivery Method - POST
Applicant information sent via an HTTP POST to a specified REST service. 
The applicant data record is delivered to a REST webservice as specified by data-posturl upon the job seeker's submission. The REST service must be able to accept the content as defined by data-deliveryformat.
Monster systems determine successful transmission by an HTTP status of either 200 or 410 returned from your rest endpoint. All other response codes will trigger the Monster retry logic. PLEASE ONLY send back error codes when the data transmission is not successful and a retry is needed. Monster automatic retries happen for any failure HTTP codes (anything besides 200 or 410) every 4 hours for 2 days.

 

Validate the authenticity of POST data

As a best practice, data received via POST from an external source should be validated to ensure its authenticity and integrity. The HTTP POST transaction request header contains two fields that are used to validate the contents of the apply data within the transaction body:

Header Field Description
AwMHash The hashed representation of the serialized apply data using HMAC-SHA1 hashing technique, and the shared secret corresponding to the API key as the hashing key
AwMApiKey API key; this is only needed if there are multiple API keys in use


To validate the transaction, independently hash the serialized apply data in the transaction body using the closely held shared secret. Take the raw body of the json/xml and hash that; do not serialize the payload. If multiple API keys exist in your environment, AwMApiKey is provided as reference to identify the corresponding shared secret to be used for the local hash calculation. The resulting locally calculated hash value is then compared with AwMHash to verify a match.

Examples of validating a hash

Example 1:

const crypto = require('crypto');
const hmacSha1Hash=Buffer.from('0mnETU+b7f7NEPahgSdrrl2DrzU=','base64'); // header AwMHash value used here
const hashKey=Buffer.from('E1THISISASAMPLESECRETVALUEFC0'); // secret value goes here
const hmac=crypto.createHmac('sha1',hashKey);

const computedHash=hmac.update(JSON.stringify({"City":"Waltham","CountryCode":"US", "EmailAddress":"monstertester@gmail.com","FileContents":[65,110,100,114,101,97,32,70,13,10],"FileExt":".rtf","FirstName":"FirstTester","JobRefID":"Testrefcode","LastName":"LastTester","PhoneNumber":"+19784026511","ResumeValue":"u3sample8jtzf","State":"MA","VendorField":"maybe blank","WorkAuthorization":1,"ZIPCode":"02453"})).digest();

console.log ("This is right after constants were defined.");
console.log ("This is the computedhash:");
console.log (computedHash);
console.log ("This is the hmacsha1hash from the header of the apply post:");
console.log (hmacSha1Hash);

// Compare bytes from hash sent in the header of post vs. hash that was computed using full payload
for (let i = 0; i < computedHash.length; i++) {
if (computedHash[i]!== hmacSha1Hash[i]) {
console.log(hmacSha1Hash);
console.log(computedHash);
throw new Error('Hash value mismatch when validating data sent - Data cannot be trusted');
}
}

Example 2:
	// Verify the HMACSHA1 hash of the data
	var apiKey = this.Request.Headers["AwMApiKey"];
	var hashData = this.Request.Headers["AwMHash"];
	var hmacSha1Hash = Convert.FromBase64String(hashData);

	// Get the hash key to use to check the hashed value
	// NOTE: This key needs to be kept private
	byte[] hashKey = Encoding.UTF8.GetBytes(GetHashKey(apiKey));
	using (HMACSHA1 hmac = new HMACSHA1(hashKey))
	{
		byte[] computedHash = hmac.ComputeHash(this.Request.InputStream);
		// Compare the bytes from the hash that was sent vs. the hash that was just generated
		// NOTE: Use the computedHash as your base comparison as that is the trusted value
			for (int i = 0; i < computedHash.Length; i++)
			{
			if (computedHash[i] != hmacSha1Hash[i])
			{
			throw new InvalidDataException("Hash value mis-match when validating data
			sent - Data cannot be trusted");
			} 			} 	}  

Samples

Sample JSON formatted Apply Record:

{
"integratedApplyId": "f66dbe51-0788-4bdd-8290-8c185fc0e14d",
"sourceAttribution": "monster",
"jobRefCode":"customers_job_id_1234abcd",
"vendorText":"text from vendor to pass along with apply",
"applicant": {
"city":"Weston",
"countryCode":"US",
"emailAddress":"applytester@monster.com",
"resume": {
"fileName": "resume-name.pdf",
"fileContents": "BASE64ENCODEDaFGP==",
"contentType": "application/pdf"
},
"firstName":"ApplicantFirstname",
"lastName":"ApplicantLastname",
"phoneNumber":"8006667837",
"region":"MA",
"workAuthorization": "0",
"postalCode":"02493"
},
"questions": [
{
"questionKey": "yearsOfExperience",
"text": "Years of experience? (e.g. 0.5-10)",
"answer": ["6.0"]
},
{
"questionKey": "haveDrivingLicense",
"text": "I have a valid driving license.",
"answer": ["true"]
},
{
"questionKey": "drivingLicense",
"text": "What type of driving license",
"answer": ["A"]
}
]
}


Sample XML formatted Apply Record: 
<applyDetailsV2>
	<integratedApplyId>f66dbe51-0788-4bdd-8290-8c185fc0e14d</integratedApplyId>
	<sourceAttribution>monster</sourceAttribution>
	<jobRefCode>customers_job_id_1234abcd</jobRefCode>
	<vendorText>text from vendor to pass along with apply</vendorText>
	<applicant>
		<city>Weston</city>
		<countryCode>US</countryCode>
		<emailAddress>applytester@monster.com</emailAddress>
		<resume>
			<fileName>resume-name.pdf</fileName>
			<fileContents>BASE64ENCODEDaFGP==</fileContents>
			<contentType>application/pdf</contentType>
		</resume>
		<firstName>ApplicantFirstname</firstName>
		<lastName>ApplicantLastname</lastName>
		<phoneNumber>1234567890</phoneNumber>
		<region>MA</region>
		<workAuthorization>0</workAuthorization>
		<postalCode>02493</postalCode>
	</applicant>
<jobRefCode>testRefCode</jobRefCode>
	<vendorText>text from vendor to pass along with apply</vendorText>
	<questions>
		<questions>
			<questionKey>license</questionKey>
			<text>Driver's licenses</text>
			<answer>
				<answer>A</answer>
				<answer>C</answer>
			</answer>
		</questions>
		<questions>
			<questionKey>expectedWeeklyHours</questionKey>
			<text>Expected weekly hours</text>
		</questions>
		<questions>
			<questionKey>openToDrugTest</questionKey>
			<text>Willing to submit to drug test?</text>
			<answer>
				<answer>true</answer>
			</answer>
		</questions>
		<questions>
			<questionKey>informationQuestion</questionKey>
			<text>Additional questions</text>
		</questions>
	</questions>
</applyDetailsV2>

 

Configuring Monster Jobs for Easy Apply Delivery to your ATS


PPC / Organic Jobs posted to Monster can be configured to use Monster's Easy Apply integration to transmit candidate information to your applicant tracking solution.

If you are just starting your apply integration you need to register for API keys for testing and production. Contact platformpartners@monster.com or your Monster Representative and make sure to include your endpoint domain to obtain your API keys.

If there is a single posturl endpoint for processing all of your jobs Monster can set a default configuration for your jobs.


  JSON job format -

  "awm": {
      "method": "Post2",
      "format": "Json",
      "apikey": "EAAQ_EXAMPLE_ONLY_MymA--",
      "vendortext": "optional field for text to pass along with apply",
      "posturl": "enter_your_REST_service_endpoint_URL_here"
        },
  "nextquestionnaire":
       {
   "url": "https://your_questions_url_goes_here"
      }


If you are ready to starting building your apply integration you need to contact platformpartners@monster.com or your Monster Representative to obtain your Easy Apply API key.