Apply Delivery Integration Guide

The following information is all about the delivery part of the Apply integration. It describes the methods, the formats and the how to steps. If you need more information about what the Monster Apply is about, please refer to Monster Apply Overview.

How do I start this integration?

If you are ready to starting building 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 both your test and production domains to obtain your API keys.

Which data delivery method should I use?

When Less is More in the application form, the greater the success. Sometimes, the fields that appear in an application form are there because of long lost reasons - they've always been there.  But with the insight that the lengthier or more complex an application form, the greater the likelihood that a prospective applicant will fail to see it through to completion, does this bit of information really need to be asked at this moment, or could it be obtained later, after initial acquisition of the candidate?  That said, the easiest, quickest, most effective integration utilizes the POST2 delivery method, also known as Easy Apply.  In circumstances where an applicant flow requires the completion of additional interview questions at the career site, the REQUEST2 delivery method can be utilized to forward the applicant interactively to the career site. This workflow is more complex than a simple POST2 integration and leads to less applicants due to drop offs. Monster's integrated apply also supports a basic EMAIL delivery method to email applicant information.

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.

string City
string CountryCode
string CoverLetter
string EmailAddress
byte[] FileContents
string FileExt
string FirstName
string JobRefID
string LastName
string PhoneNumber
string ResumeValue
string State
string VendorField
string WorkAuthorization
String ZipCode


Field Notes
CoverLetter This is simply a string, not an attachment.
JobRefID This is the jobrefcode sent in on a job posted to Monster. It is the customer's identification for the job.
VendorField This is the text value optionally provided in the VendorText sent in on the job posted to Monster.
FileExt This identifies the file extension for the resume document contained in the fileContents byte stream. Possible values are: .doc, .docx, .pdf, .rtf, .txt, and .html.
CountryCode This is the 2 letter ISO value for the country.
ResumeValue This is a unique alpha numeric value on the Monster side.
WorkAuthorization This is a value of whether the applicant is authorized to work in the country provided in the countryCode
FileContents This contains the resume in its original format as it was made available by the applicant. It is a C#, unsigned Byte Array. If the resume was created interactively on Monster, the resume is provided as consistently formatted HTML. If an applicant originally uploaded a resume to Monster (e.g., as a PDF), it is delivered in the original document format. Resume size can be up to 10 MB. Due to some additional data and overhead coming from the serialization / deserialization process, XML format should be set to accept up to 8 MB/ JSON format should be set to accept up to 20 MB.

Example Apply Record in JSON format:


{
"City":"Weston",
"CountryCode":"US",
"CoverLetter":"This is a cover letter. It is simply sent as text.",
"EmailAddress":"applytester@monster.com",
"FileContents":[80,75,3,4,20,0,0,0],
"FileExt":".docx",
"FirstName":"ApplicantFirstname",
"JobRefID":"customers_job_id_1234abcd",
"LastName":"ApplicantLastname",
"PhoneNumber":"8006667837",
"ResumeValue":"jj34hffti6v",
"State":"MA",
"VendorField":"text from vendor to pass along with apply",
"WorkAuthorization":3,
"ZIPCode":"02493"
}



Example Apply Record in XML format:


<ApplyRecord xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<FirstName>ApplicantFirstName</FirstName>
<LastName>ApplicantLastName</LastName>
<EmailAddress>testseeker@something.com</EmailAddress>
<PhoneNumber>8006667837</PhoneNumber>
<CoverLetter>This is a cover letter. It is simply sent as text</CoverLetter>
<JobRefID>andrea_awm_sample_xml</JobRefID>
<FileContents>ABD_This_is_base64_format_PCEtLUhUTUxSZW5kZXJlci0tPg0KDQoNCiAgDQoJDQoJCTwhLS1SZXN1bWVOYXZpZ2F</FileContents>
<FileExt>.docx</FileExt>
<ResumeValue>c7z7sampleh448gc</ResumeValue>
<CountryCode>US</CountryCode>
<ZIPCode>02493</ZIPCode>
<City>Weston</City>
<State>MA</State>
<WorkAuthorization>1</WorkAuthorization>
</ApplyRecord>




Delivery Methods

There are three different methods for obtaining an applicant's submitted information:


Delivery Method Description
POST2 Applicant information sent via a POST to a specified REST service. This is also called Easy Apply and the seeker remains on the Monster site.
REQUEST2 On notification of applicant submission, the client system makes a web service request to obtain the applicant information. The seeker has to accept the redirection off to another site and the risk of drop off heightens. 
EMAIL An email is delivered to the specified email address.


Receiving applicant information via POST2 method

HTTP POST to a REST webservice is a common and most recommended method for accepting applicant information for subsequent processing. If the data-deliverymethod is set to "POST2", the applicant information 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.

The Content-Type sent for JSON using POST2 is application/json, and for xml is always "text/xml". The REST endpoint needs to accept the content type associated with the delivery format requested.

The POST URL specified by data-posturl can be specified in clear ASCII format:

data-posturl="https://www.myats.com/awm/apply"

or its Base64 equivalent:

data-posturl="aHR0cDovL3d3dy5teWF0cy5jb20vYXdtL2FwcGx5"

Take Note!

The domain of a target data-posturl must be registered for use with the referenced data-api-key for the Apply with Monster button to display.



Validate the authenticity of POST2 data

As a best practice, data received via POST2 from an external source should be validated to ensure its authenticity and integrity. The HTTP POST2 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. 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.

  Example of validating a hash

…
	// 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");
			}
			}
	}
…

Receiving applicant information via email

Email is the simplest way to start receiving applicant information. If data-deliverymethod is set to "EMAIL", applicant information is delivered to the email address named in data-emailaddress. The email address named in data-emailaddress can be specified in clear ASCII format:

data-emailaddress="applicant@myats.com"

or its Base64 equivalent:
data-emailaddress="YXBwbGljYW50QG15YXRzLmNvbQ=="


Take Note!

Optional Base64 encoding serves as a handy lightweight technique to help avoid potential harvesting by email scrapers. It is not an encryption scheme, nor a foolproof obfuscation scheme for a determined harvester.


With email delivery method, the applicant information email is provided in HTML format with the resume and cover letter provided as attachments. For ease of optional post-processing, the job and applicant information contained within the email body is also provided as an attachment, formatted as specified by data-deliveryformat. If data-deliveryformat is not specified, JSON format is defaulted.

 
If EMAIL delivery method is utilized, there is no further processing necessary; an applicant's resume and cover letter are provided in their original formats as email attachments.

The domain of a target data-emailaddress must be registered for use with the referenced data-api-key for the Apply with Monster button to display. As an alternative to registering each new customer's domain(s), it may be more efficient to configure data-emailaddress to <newcompanyname@yourregistereddomain> and forward the email to the intended target email address.


Obtaining application information via REQUEST2 Method

Applicant information can also be obtained on request via HTTP GET. This method might be preferable if the applicant information is needed synchronously in advance of ensuing steps. When a data-deliverymethod of "REQUEST" is specified, the JavaScript callback specified by data-onsuccess is also required. For this usage, the success event returns an additional element, req.requestUrl.

The requestUrl field is the target URL-encoded URL for where to make a HTTP GET request to retrieve the applicant's information. To authenticate requestors, when making the HTTP GET request, the shared secret that you obtained with your API key must be appended as an additional parameter, in the format, "&stoken=<yourSharedSecret>" ,e.g.,

Sample HTTP GET request:

https%3a%2f%2flogin20.monster.com%2fAwm%2fApplyRecord%3fapikey%3dEAAQ33Nb18vQ34xbnqYiR2KayESo9mwTmdI9MsrWNfAK9q4-%26adt%3dEAAQbLTWk.pUfmRb5dAUyfsnWxKWADzVmXvYNzAMK67_8gBEIXiNG4O.XOJgih1ryKveZXvNxWDzLhrqGwN_ ... v6GJq4FD4goGSCB9LKFX_7cq6fMHvhqsM1T_DbxvOeWOwUfzmCHs2.6pbRSK6idqUtq8ygffLlDIhA9c0-%26stoken%3d12345


This call will return the applicant information in response.

Take Note!

Applicant information is expected to be retrieved shortly after submission notification. After 24 hours, applicant information is no longer retrievable.

Samples


Example of deserializing XML data

…
using System.Xml.Serialization;
…
                ApplyRecord am = new ApplyRecord();
                if (this.Request.ContentType == "text/xml")
                {
                    XmlSerializer xml = new XmlSerializer(typeof(ApplyRecord));
                    am = (ApplyRecord)xml.Deserialize(this.Request.InputStream);
                }


Example of deserializing JSON data

…
using System.Runtime.Serialization.Json;
…
                {
                    DataContractJsonSerializer djs = new DataContractJsonSerializer(typeof(ApplyRecord));
                    am = (ApplyRecord)djs.ReadObject(this.Request.InputStream);
                }


Sample JSON format from POST2:


{
"City":"Weston",
"CountryCode":"US",
"CoverLetter":"This is a cover letter. It is simply sent as text.",
"EmailAddress":"applytester@monster.com",
"FileContents":[80,75,3,4,20,0,0,0],
"FileExt":".docx",
"FirstName":"ApplicantFirstname",
"JobRefID":"customers_job_id_1234abcd",
"LastName":"ApplicantLastname",
"PhoneNumber":"8006667837",
"ResumeValue":"jj34hffti6v",
"State":"MA",
"VendorField":"text from vendor to pass along with apply",
"WorkAuthorization":3,
"ZIPCode":"02493"
}


Sample XML format from POST2:
<ApplyRecord xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<FirstName>ApplicantFirstName</FirstName>
<LastName>ApplicantLastName</LastName>
<EmailAddress>testseeker@something.com</EmailAddress>
<PhoneNumber>8006667837</PhoneNumber>
<CoverLetter>This is a cover letter. It is simply sent as text</CoverLetter>
<JobRefID>andrea_awm_sample_xml</JobRefID>
<FileContents>ABD_This_is_base64_format_PCEtLUhUTUxSZW5kZXJlci0tPg0KDQoNCiAgDQoJDQoJCTwhLS1SZXN1bWVOYXZpZ2F</FileContents> <FileExt>.docx</FileExt>
<ResumeValue>c7z7sampleh448gc</ResumeValue>
<CountryCode>US</CountryCode>
<ZIPCode>02493</ZIPCode>
<City>Weston</City>
<State>MA</State>
<WorkAuthorization>1</WorkAuthorization>
</ApplyRecord>

HTML Sample - here is an example of a resulting html file after deserializing the FileContents field for a resume that was created interactively at the Monster site (e.g., not uploaded as a .doc or .pdf):

<!--HTMLRenderer--> <!--ResumeNavigationLinks--> <!--ResumeInstructionalText--> <!--Referral--> <!--ContactInfo--> <table border="0" cellspacing="0" cellpadding="0" width="650" xmlns:fo="https://www.w3.org/1999/XSL/Format" xmlns:m="https://schemas.monster.com/Monster" xmlns:ms="urn:schemas-microsoft-com:xslt" /> <!--Title--> <table border="0" cellspacing="0" cellpadding="0" width="650" xmlns:fo="https://www.w3.org/1999/XSL/Format"> <tr> <td><a name="resume"> <table cellspacing="0" cellpadding="0" border="0" width="100%" class="sectionHeaderBackground"> <tr> <td width="180" style="height:1px; width:180px;" /> <td colspan="2" style="height:1px; width:470px;" /> </tr> <tr style="background-color:#e5ecf3;"> <td height="18" width="180"><span class="boldText">RESUME</span></td> <td height="18" class="SmallText" align="left">  </td> <td height="18" align="right" class="smallBoldText" /> </tr> </table> </a></td> </tr> <tr> <td height="15" /> </tr> <tr> <td colspan="2" class="SmallText" style=" padding-left:7px; "><table border="0" cellspacing="0" cellpadding="0" width="100%"> <tr> <td align="left"><span class="boldText">Resume Headline: </span> <ResumeTitle>af_built</ResumeTitle></td> <td align="right"><span class="boldText">Resume Value: </span> <ResumeValue>ncr3894r3kmhfazs</ResumeValue>    </td> </tr> </table>   </td> </tr> <tr> <td height="15" style="border-top:1px solid #e5ecf3;" /> </tr> </table> <!--Summary--> <!--Experience--> <table border="0" cellspacing="0" cellpadding="0" width="650" xmlns:fo="https://www.w3.org/1999/XSL/Format"> <tr> <td class="boldText" valign="top" style="padding-left:7px;" width="180">EXPERIENCE:</td> <td class="smallText" valign="top" width="150">6/2008 - Present</td> <td class="smallText" valign="top" width="150"><Company>Monster</Company></td> <td class="smallText" valign="top" width="150"><Location /></td> </tr> <tr> <td class="boldText" valign="top" style="padding-left:7px;" width="180"></td> <td class="smallText" valign="top" colspan="3" width="450"><b> <ExperienceTitle>Support</ExperienceTitle> </b></td> </tr> <tr> <td height="15" /> </tr> <tr> <td class="boldText" valign="top" style="padding-left:7px;" width="180"></td> <td class="smallText" valign="top" colspan="3" width="450" /> </tr> <tr> <td height="15" /> </tr> </table> <!--Education--> <!--Certification--> <!--Skill--> <!--Language--> <!--Award--> <!--CAREER HIGHLIGHT--> <!--Interest--> <!--Affiliation--> <!--Reference--> <!--CustomFields-->