Easy 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. 

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.

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.
   
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.

 

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-->

Configuring Monster jobs for Easy Apply delivery to your ATS


Jobs posted to Monster can be configured to use Monster's Easy Apply integration to transmit candidate information to your applicant tracking solution.  If there is a single endpoint for processing all of your jobs and therefore a single configuration setting, contact Monster, and we can set the default configuration for your for your company - this is the most common implementation. 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 domains to obtain your API keys.

When an applicant delivery method is specified within your RTP elements, the parameter set must include all required fields necessary per your particular configuration. For example, if the DeliveryMethod is set to POST2, a PostURL is required. The PostURL would also need to be a valid registered domain for the referenced ApiKey.

Values for the DeliveryMethod and DeliveryFormat:



<xsd:simpleType name="AwmDeliveryMethodIdEnum">
- <xsd:annotation>
<xsd:documentation>  2 EMAIL       5 POST2 


<xsd:simpleType name="DeliveryFormatIdEnum">
- <xsd:annotation>
<xsd:documentation>1 JSON     2 XML</xsd:documentation>


For more schematic details on these, go to the Monster enumerations schema located here. Simply search for “AwmDeliveryMethod” and "AwmDeliveryFormat". 

Take Note!  EmailAddress and PostURL in the RTP schema do not support the optional Base64 encoding of data-emailaddress and data-posturl, respectively.

Example of a POST2 delivery elements within RTP job specification



</JobBody>
<ApplyWithMonster>
<DeliveryMethod monsterId="5"/>
<DeliveryFormat monsterId="1"/>
<VendorText>This apply comes from a job on Monster</VendorText>
<PostURL>https://jobapply.atsendpoint.com/api/jobapplymonster</PostURL>
<ApiKey>EAAQLKS_bP0Z_sample_only_w--</ApiKey>




Testing your integration

1. Use your testing API key so that reporting will not be affected and use the testing job board id so that real job seekers don't inadvertently find your job and apply to it.
2. Test your job posting to Monster using the testing board id 178 with your Testing Api Key and selections for method and format of delivery. Refer to RTP Testing instructions for more information on posting to the testing board.
3. Use an existing seeker account  or create one on Monster's site and create a resume. Make the resume inactive so it won't be searchable by recruiters.
4. Go to the jobview URL and click the Apply with Monster button, and sign into your job seeker account.
5. Complete Apply process for this test seeker, and close the Apply modal dialogue.
6. Verify that your service is able to receive the applicant information according to your specified delivery method. If using:
7. Repeat the Apply flow with various combinations of different resume document types (e.g., .doc, .docx, .pdf) and including and excluding a cover letter to simulate a wide range of applicant characteristics that you will encounter.