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?
string City
string CountryCode
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 |
|---|---|
| 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. For JSON delivery format it is provided as a C#, unsigned Byte Array. For XML delivery format it is provided as base64. 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. |
Delivery Methods
There are two 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. |
| 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 is specified like this: data-posturl="https://www.myats.com/awm/apply"
Take Note!
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 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.
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");
}
}
}
…
Receiving applicant information via Email method of Easy Apply
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 provided as an attachment. 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 is provided in its original format as an email attachment.
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",
"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>
<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>
<VendorField>text from vendor to pass along with apply</VendorField>
<WorkAuthorization>1</WorkAuthorization>
</ApplyRecord>
Configuring Monster Jobs for Easy Apply Delivery to your ATS
Jobs posted to Monster can all 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 endpoint for processing all of your jobs, contact Monster, and we can set the default configuration for your company.
For PPC / Organic jobs use these fields:
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_URL_here"
}
XML job format -
<awm>
<method>Post2</method>
<format>Json</format>
<apikey>EAAQ_EXAMPLE_ONLY_MymA--</apikey>
<vendortext>optional field for text to pass along with apply</vendortext>
<posturl>enter_your_REST_service_URL_here</posturl>
</awm>
For Real Time Posted (Duration) jobs use these fields:
<applywithmonster>
<deliverymethod monsterid="5"></deliverymethod>
<deliveryformat monsterid="1"></deliveryformat>
<vendortext>optional field for text to pass along with apply</vendortext>
<posturl>enter_your_REST_service_URL_here</posturl>
<apikey>EAAQ_EXAMPLE_ONLY_MymA--</apikey>
</applywithmonster>
NOTE per the schemas:
<xsd:simpleType name="AwmDeliveryFormatIdEnum">
<xsd:annotation>
<xsd:documentation> 1 JSON 2 XML </xsd:documentation>
Testing your integration
1. Use your testing API key so that reporting will not be affected.2. Post a job to Monster with your Testing Api Key and values for POST2 method, format and testing endpoint URL.
3. Wait for job to be viewable, which can take a couple of hours.
4. 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.
5. Go to the jobview URL and click the Apply button, and sign into your job seeker account.
6. Complete Apply process for this test seeker, and close the Apply modal dialogue.
7. Verify that your service is able to receive the applicant information.