Snagajob's Public API Documentation
HomeAuthentication
  • Welcome to Snagajob's Developer Documentation
  • Authentication
    • Obtaining API Access
    • Generating the X-SAJ-Signature
  • Posting Creation
    • XML Feed Reference
    • Single - Uploading an XML Job Feed to Snagajob
    • Bulk - Uploading an Aggregate XML Job Feed to Snagajob
  • Easy Apply
    • Adding Support for Snagajob's Easy Apply
  • Job Sponsorship
    • Sponsoring Postings via Snagajob's Sponsorship API
    • Adding Sponsorship Campaigns to your XML Feed
  • Data Sharing
    • Receiving Click Data From Snagajob
      • Receiving Click and Cost Data via HTTP Requests
      • Receiving Click and Cost Data via an sFTP
    • Sending Application Complete Events Back to Snagajob
    • Sending Candidate Disposition Data to Snagajob
Powered by GitBook
On this page
  • Brief Process Overview
  • Adding Easy Apply to your XML Feed
  • Using Screening Questions
  • JSON for screening questions
  • Application Data Delivery
  • PostUrl
  • Sample JSON of Application Data from Snagajob
  • Candidate Data Field Descriptions
  • Validating the Posts Authenticity

Was this helpful?

  1. Easy Apply

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.

PreviousBulk - Uploading an Aggregate XML Job Feed to SnagajobNextSponsoring Postings via Snagajob's Sponsorship API

Last updated 1 year ago

Was this helpful?

Before implementing Easy Apply, please fill out our 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

  1. You pass us job postings via an XML feed with the qualifications per requisition.

  2. You pass us an endpoint URL (per job) via your feed within the <PostUrl>XML element

    1. Example: <PostUrl>https://myapplicantapi.com/sajeasyapply</PostUrl>

  3. (Optional) You pass us a URL containing JSON formatted screening questions in the <ScreeningQuestionsUrl> element per job.

  4. We post your jobs and enable our Easy Apply application experience.

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

Please reference for a list of XML feed elements to add to your feed files to enable Easy Apply.

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:

<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

Name
Required
Description
Allowed values
Example

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": "first.last@testing.com",
    "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

Value
Always provided?
Description
Type

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\":\"john.doe@example.com\"}";
    }
}
Vendor Intake Form
Easy Apply feed elements
Single Customer Feed XML Example