Adding Support for Snagajob's Easy Apply
This resource contains integration instructions for our ATS partners. Enabling Easy Apply lets applicants use their Snagajob profile to apply to jobs.
Before implementing Easy Apply, please fill out our Vendor Intake Form to obtain your API secret and become a registered partner with Snagajob. We will not pass Easy Apply application data to unregistered partners.
Brief Process Overview
You pass us job postings via an XML feed with the qualifications per requisition.
You pass us an endpoint URL (per job) via your feed within the
<PostUrl>XML elementExample:
<PostUrl>https://myapplicantapi.com/sajeasyapply</PostUrl>
(Optional) You pass us a URL containing JSON formatted screening questions in the
<ScreeningQuestionsUrl>element per job.We post your jobs and enable our Easy Apply application experience.
We send the application data back to the PostUrl each time a worker applies. Data is transmitted to the URL specified in the
<PostUrl>element.
Adding Easy Apply to your XML Feed
Converting your postings to Easy Apply allows workers to apply to your jobs directly on Snagajob with their profile.
To convert your postings to Easy Apply, partners must add a <PostUrl> XML element to each job in their feed containing an HTTPS endpoint that Snagajob should POST applications to.
See this XML example: Single Customer Feed XML Example
<PostUrl>https://myapplicantapi.com/where-applications-should-go</PostUrl>
Using Screening Questions
Format screener questions in JSON and post them to a URL (HTTPS) included for each <Item> in the <ScreeningQuestionsUrl> element. Snagajob does not host screening questions on your behalf.
<ScreeningQuestionsUrl>https://myapplicantapi.com/where-we-find-questions</ScreeningQuestionsUrl>
JSON for screening questions
This section lists the parameters used in building all question types. For examples of specific question types, refer to Screening question types.
Screening question parameters
id
Yes
Unique ID for this question.
any string
question-123
type
Yes
Describes the type of question.
select multiselect textarea
textarea
question
Yes
The question text that applicants see.
any string
Are you 18 years or older?
options
Yes for type=select and type=multiselect
The list of options available for the worker to answer.
JSON
[{ "value":"1", "label":"Yes" },
{ "value":"2", "label":"No" }]
value
Yes for type=select and type=multiselect
The value corresponds to each option returned for questions with multiple options.
any string
1
label
Yes for type=select and type=multiselect
The text displayed for each corresponding option.
any string
Yes
required
No
Allows you to set a question as required. When required:true is present, Snagajob forces a non-empty text field or a non-empty selection.
boolean
"required":true
format
No
The accepted format of the input. If left null , we will default to a string type.
Supported type enforcement: - integer - decimal
”format“: “integer”
condition
No
Marks a question as conditional, depending on the answer to a previous select question. Specify the id of the previous question and the option value that activates this question.
For example, you might ask applicants if they’ve previously worked for a specific employer. Then, depending on their selection, you could offer another question to describe their experience.
JSON
"condition": { "id": "parent", "value": 0}
Screening question types
select
This is a question type that presents all available options and allows the respondent to choose a single answer. Used for questions that should only have one answer.
Example:
{
"id": "gender",
"type": "select",
"question": "What is your gender?",
"required": true,
"options": [{
"value": "0",
"label": "Decline to answer"
},
{
"value": "1",
"label": "Male"
},
{
"value": "2",
"label": "Female"
}
]
}multiselect
This is a multiple-choice question that allows the user to select multiple answers.
Example:
{
"id": "availability",
"type": "multiselect",
"question": "Select the days you are available to work.",
"required": true,
"options": [{
"value": "0",
"label": "Monday"
},
{
"value": "1",
"label": "Tuesday"
},
{
"value": "2",
"label": "Wednesday"
},
{
"value": "3",
"label": "Thursday"
},
{
"value": "4",
"label": "Friday"
},
{
"value": "5",
"label": "Saturday"
},
{
"value": "6",
"label": "Sunday"
}
]
}textarea
A question that displays a text entry field.
Example:
{
"id": "color",
"type": "textarea",
"question": "Whats your favorite color?",
"required": true
}Making questions conditional
This is a question that may or may not be displayed based on the responses to previous questions. For instance, you may inquire if the applicants have worked for a particular employer before. Then, depending on their answer, you could present another question to have them describe their experience.
Example:
[
{
"id": "previous-employment",
"type": "select",
"question": "Have you worked for this employer in the past?",
"required": true,
"options": [
{
"value": "0",
"label": "Yes"
},
{
"value": "1",
"label": "No"
}
]
},
{
"id": "please-explain",
"type": "textarea",
"question": "If yes, please explain your experience there.",
"required": true,
"condition": {
"id": "previous-employment",
"value": "0"
}
}
]Application Data Delivery
To accept candidate data via API, you must include a POST URL on each posting in the XML feed you wish to accept programmatically.
PostUrl
Specify a URL where Snagajob will send a POST request containing the application data. Must be HTTPS.
Example URL:
<PostUrl>https://myapplicantapi.com/where-applications-should-go</PostUrl>
Sample JSON of Application Data from Snagajob
{
"id": "applicationId12345",
"applicantAddress": {
"line1": "123 Main St.",
"line2": "",
"city": "Richmond",
"stateProvCode": "VA",
"postalCode": "23219"
},
"emailAddress": "[email protected]",
"employment": [
{
"employerName": "We Paint Cars",
"endDate": null,
"jobTitle": "Automotive Painter",
"startDate": "2019-01-01T05:00:00Z"
},
{
"employerName": "Local Library",
"endDate": "2018-05-01T04:00:00Z",
"jobTitle": "Librarian",
"startDate": "2015-01-01T05:00:00Z"
},
{
"employerName": "Fast Food Chicken Chain",
"endDate": "2014-12-01T05:00:00.00Z",
"jobTitle": "Assistant Manager",
"startDate": "2011-07-01T04:00:00Z"
}
],
"firstName": "First",
"lastName": "Last",
"fullName": "First Last",
"isAuthorizedToWorkInUs": true,
"phoneNumber": "8045551234",
"ipAddress": "1.1.1.1",
"userAgent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:35.0) Gecko/20100101 Firefox/35.0",
"qualifications": [
{
"displayText": "Background check",
"isPass": true,
"name": "q-basic-bgcheck",
"required": false
},
{
"displayText": "14 years or older",
"isPass": true,
"name": "q-basic-dob",
"option": 1,
"required": true
},
{
"displayText": "Legally authorized to work in the United States",
"isPass": true,
"name": "q-basic-auth",
"required": true
},
{
"displayText": "At least associate's degree or higher",
"isPass": true,
"name": "q-exp-degree",
"option": 2,
"required": true
}
],
"requisitionId": "req12345",
"resume": {
"contentType": "application/pdf",
"data": "U25hZ2Fqb2I="
},
"questionsAndAnswers": [
{
"question": {
"id": "gender",
"question": "What is your gender?",
"type": "select",
"required": true,
"options": [
{
"value": "0",
"label": "Decline to answer"
},
{
"value": "1",
"label": "Male"
},
{
"value": "2",
"label": "Female"
}
]
},
"answer":{
"selectedAnswers": [
{
"value": "2",
"label": "Female"
}
]
}
},
{
"question": {
"id": "availability",
"question": "Select the days you are available to work.",
"type": "multiselect",
"required": true,
"options": [
{
"value": "0",
"label": "Monday"
},
{
"value": "1",
"label": "Tuesday"
},
{
"value": "2",
"label": "Wednesday"
}
{
"value": "3",
"label": "Thursday"
},
{
"value": "4",
"label": "Friday"
},
{
"value": "5",
"label": "Saturday"
},
{
"value": "6",
"label": "Sunday"
}
]
},
"answer": {
"selectedAnswers": [
{
"value": "4",
"label": "Friday"
},
{
"value": "5",
"label": "Saturday"
},
{
"value": "6",
"label": "Sunday"
}
]
}
},
{
"question": {
"id": "color",
"type": "textarea",
"question": "Whats your favorite color?",
"required": true
},
"answer": {
"answerText": "blue"
}
}
]
}Candidate Data Field Descriptions
Applicant Fields Table
id
Yes
Unique ID for the application
string
applicantAddress
Partially
JSON object representing the user's location.
object
applicantAddress.line1
No
The address line 1 of the Candidate’s address
string
applicantAddress.line2
No
The address line 2 of the Candidate’s address
string
applicantAddress.city
No
The city of the Candidate’s address
string
applicantAddress.stateProvCode
No
The state province code of the Candidate’s address
string
applicantAddress.postalCode
Yes
The postal code of the Candidate’s address
string
emailAddress
Yes
The email address of the Candidate.
string
employment
No
JSON object representing the user's work history.
object
employment.employerName
No
The company's name.
string
employment.endDate
No
A string containing a timestamp representing the ending employment date.
string
employment.jobTitle
No
The title of the job.
string
employment.startDate
No
A string containing a timestamp representing the starting employment date.
string
firstName
Yes
The first name of the Candidate.
string
lastName
Yes
The last name of the Candidate.
string
fullName
Yes
The full name of the Candidate.
string
isAuthorizedToWorkInUs
No
Boolean field indicating a Candidates eligibility to work in the US.
boolean
phoneNumber
Yes
The phone number of the Candidate.
string
[Obsolete] qualifications
No
JSON object representing the user's qualification question answers. This object will continue to be present as vendors transition to the new questionsAndAnswers object, but will eventually be depreciated.
object
[Obsolete] qualifications.displayText
No
This is the question displayed to the worker.
string
[Obsolete] qualifications.isPass
No
"isPass": true means the worker answered Yes to the question "isPass": false means the worker answered No to the question
boolean
[Obsolete] qualifications.name
No
The name of the qualification
string
[Obsolete] qualifications.required
No
This field signifies if the employer requires the worker to answer 'Yes' ("isPass": true) to be qualified for the role.
boolean
[Obsolete] qualifications.option
No
For Scaling (Type 3) questions, the employer can ask multiple variations of the same question (For example, asking if the worker has more than one type of food certification). This field indicates which answer the isPass answer corresponds to.
int
requisitionId
Yes
The requisition id of the job the Candidate is applying to. This id will match the id value passed into the feed.
string
resume
Yes
JSON object representing Candidate’s resume.
object
resume.contentType
Yes
The content type identified using the resume file's extension.
string
resume.data
Yes
The file's raw binary bytes encoded using base 64.
string
questionsAndAnswers
No
JSON object representing the user's screening questions and answers as outlined above
object
questionsAndAnswers.question
No
JSON object containing the question details
object
questionsAndAnswers.question.id
No
Unique ID for the question
string
questionsAndAnswers.question.question
No
The question text that applicants see.
string
questionsAndAnswers.question.type
No
Describes the type of question.
string
questionsAndAnswers.question.required
No
Identifies if the question contained a required input
boolean
questionsAndAnswers.question.options
No
The list of options that were available for the worker to answer.
array
questionsAndAnswers.answer
No
JSON object containing the answer details
object
questionsAndAnswers.answer.selectedAnswers
No
The answer options selected by the Worker. Note: This field will only be populated for questions with a ”type”:”select” and ”type”:”multiselect”
array
questionsAndAnswers.answer.answerText
No
The answer text that was submitted by the Worker. Note: This field will only be populated for questions with a ”type”:”textarea”.
string
ipAddress
No
The IP address of the Candidate’s device
string
userAgent
No
The user agent of the Candidate’s device
string
Validating the Posts Authenticity
Snagajob signs each application post request made to your PostUrl with the HTTP header X-SAJ-Signature that partner can use to verify the post's authenticity. Snagajob Easy Apply computes the message signature using the HMAC-SHA1 algorithm using the shared API secret. This signature is sent as an X-SAJ-Signature HTTP header. An X-SAJ-Date HTTP header is also included and should be used to ignore any requests over 15 minutes old.
The code examples below demonstrate how the message signature is generated.
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
public class Program
{
public static void Main(string[] args)
{
string requestBody = GetRequestBody();
string apiSecret = "your api secret key";
string requestXSAJDate = "Thu, 13 Jan 2022 17:21:07 GMT";
string signature = ComputeSignature($"{requestBody};{requestXSAJDate}", apiSecret);
if (signature.Equals("AIAvMLdPqjbNocJ4UHZpg3Axxzk="))
{
Console.WriteLine("B64 HMAC SHA1: " + signature);
}
else
{
Console.WriteLine("invalid value: " + signature);
}
}
private static string ComputeSignature(string input, String key)
{
byte[] keyBytes = Encoding.UTF8.GetBytes(key);
using(HMACSHA1 myhmacsha1 = new HMACSHA1(keyBytes))
{
byte[] inputBytes = Encoding.UTF8.GetBytes(input);
byte[] hash = myhmacsha1.ComputeHash(inputBytes);
return Convert.ToBase64String(hash);
}
}
private static string GetRequestBody()
{
return "{\"firstName\":\"John\", \"lastName\":\"Doe\", \"fullName\":\"John Doe\", \"email\":\"[email protected]\"}";
}
}Last updated
Was this helpful?