Sending Candidate Disposition Data to Snagajob

This resource contains instructions for vendors interested in uploading a disposition data file directly to Snagajob.

What is disposition data?

Disposition data is any update to an application in your Applicant Tracking System (ATS).

Why should I send disposition data to Snagajob?

We request this for our Workers. For our Workers, understanding the status of their application is crucial, so we want to keep them in the loop. When partners provide us with disposition data, we reward responsive employers with better positioning in search results, distinct badging, and exclusive inventory slots, which leads to higher application volume.

Distinct badging for active employers

How do I upload disposition data?

1. Obtain a pre-signed URL by calling our public API route.

2. Upload your feed file to our S3 bucket using our example format

post

Header parameters

X-SAJ-PartnerstringOptional

A key provided by Snagajob that represents the partner. Required.

X-SAJ-DatestringRequired

The date and time of the request in the RFC1123 format (eg: Mon, 31 Oct 2022 20:23:10 GMT). Dates older then 15 minutes will be rejected.

X-SAJ-SignaturestringRequired

A string specific to the request and signed with a private key as described https://docs.snagajob.com/authentication/generating-the-x-saj-signature".

Responses

200

OK

application/jsontext/json

post

HTTPcURLJavaScriptPython

POST /v1/presigned-s3-disposition-post HTTP/1.1
Host: 
X-SAJ-Date: text
X-SAJ-Signature: text
Accept: */*

200

OK

{
  "url": "https://example.com",
  "fileUrl": "https://example.com",
  "fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Example Request

curl 'https://developers.snagajob.com/api/v1/presigned-s3-disposition-post' \
    -X POST	
    -H 'X-SAJ-Account: Partner GenericAts' \
    -H 'X-SAJ-Signature: <base64 encoded signature>' \
    -H 'X-SAJ-Date:  Mon, 31 Oct 2022 20:23:10 GMT'

Example Response

{
   "fields" : {
      "key" : "some_path/to_a_file/PP_GenericAts_20220413190807.csv",
      "policy" : "<policy-value>",
      "success_action_status" : "201",
      "x-amz-algorithm" : "AWS4-HMAC-SHA256",
      "x-amz-credential" : "AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request",
      "x-amz-date" : "20220420T000000Z",
      "x-amz-security-token" : "<security-token>",
      "x-amz-signature" : "<signature-value>"
   },
   "fileUrl" : "https://examplebucket.s3.amazonaws.com/some_path/to_a_file/PP_8675309_20220420190807.csv",
   "url" : "https://examplebucket.s3.amazonaws.com"
}

Request to upload your disposition data CSV

The above response has all the necessary information to upload your CSV directly to a Snagajob S3 bucket.

Below is an example of what that request looks like:

curl 'https://examplebucket.s3.amazonaws.com' \
    -F policy=<policy-value> \
    -F success_action_status=201 \
    -F key=some_path/to_a_file/PP_8675309_20220420190807.csv\
    -F x-amz-algorithm=AWS4-HMAC-SHA256 \
    -F x-amz-credential=AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request \
    -F x-amz-signature=<signature-value> \
    -F x-amz-security-token=<security-token> \
    -F x-amz-date=20220420T000000Z \
    -F file=@the_file_you_would_like_to_upload.csv

Note: The presigned post information is only valid for 5 minutes. If you attempt to upload a file with expired presigned post information, you’ll receive an Unauthorized response from Amazon.

File Details and Requirements

File Details

• Upload format: .csv

• Upload size: Up to 1GB of data per upload. For larger files, please break them up into multiple files.

• Minimum upload frequency: Daily

• Maximum upload frequency: Up to once per hour

CSV column field definitions

Field	Required?	Description
apply_id	Yes	The unique identifier for the job application is used to reference the employer, candidate, job, and more. This is the id field in the Easy Apply JSON application data. (See Example JSON)
disposition_timestamp	Yes	ISO 8601 format timestamp with timezone information for when the status change occurred.
status	Yes	The status of an application.

Supported Disposition Statuses

Status	Description
NEW	The application arrived via Easy Apply
CONTACTED	The candidate was contacted by phone, email, etc. This status should be sent even if the application status on your ATS has not changed. Snagajob uses this as a signal to help determine employer responsiveness, influencing the rank of your client’s jobs. (See Why should I send disposition data to Snagajob?)
INTERVIEWED	The candidate has been interviewed.
OFFERED	An offer of employment has been sent to a candidate.
HIRED	The candidate accepted an offer of employment.
REJECTED	A candidate has been explicitly rejected, or all remaining candidates rejected after the role closed.

Example CSV

apply_id	disposition_timestamp	status
app01	2019-01-02T01:00:00Z	NEW