header
Talent.com
Disposition Data Guide
Integrate the Disposition Data API into your ATS (Applicant Tracking System).
xml-feeds
What is disposition data?
arrow
Why should I send disposition data to Talent.com?
How do I upload disposition data to Talent.com?
talent-apply
What are the steps of the integration process?
questions
API requirements
arrow
Standard integration setup
Field definitions
data-delivery
API instructions for exporting data to Talent.com
arrow
Integration
Obtaining a signed S3 URL
Required request headers
Parameters
Limitations
Success response
Error response
Uploading files
Code examples
talent-apply
Frequently asked questions
talent-apply
Need assistance?
talent-apply
Disclaimer
What is disposition data?
Disposition data consists of all the status changes that occur in the recruitment workflow of an application in an Applicant Tracking System (ATS).

This includes all major steps of the hiring funnel, performed either by the recruiter or by the applicant.
Examples of disposition data:
  • A new job seeker entered the ATS
  • A job seeker was:
    • Contacted
    • Interviewed
    • Given an offer
    • Rejected
    • Hired
Why should I send disposition data to Talent.com?
  • By providing valuable disposition data feedback on the quality of applications sent, Talent.com can optimize the quality and volume of applications we send in the future.

  • Talent.com can use this feedback to enhance the job seeker experience by:
    • Displaying jobs in need of more applications
    • Highlighting employers with the best practices regarding candidate experience
    • Better matching jobs by displaying opportunities to job seekers where their profile is more likely to be successful


How do I upload disposition data to Talent.com?
  • First, set up Talent Apply so we can send applicants and application data to your ATS via API.
  • If the current integration of your ATS with Talent.com requires the applicant to be redirected to a form on an external page before applying, then you need to implement Talent Apply first.
  • Get in touch with us at integrations@talent.com. to request a Disposition Data Integration. Please check the API requirements, the API instructions, and the integration process summary below to see if you can comply.
  • Please make sure to mention any potential issues to your Talent.com manager if you're unable to comply.
What are the steps of the integration process?
  1. Contact your partnership manager at Talent.com (or send an email to integrations@talent.com) to check the initial requirements and start the process.
  2. You will receive a set of API keys via email from Talent.com. They can only be used for the purpose of Talent.com Disposition Data Integration.
  3. Read all our documentation below.
  4. Test your API key by uploading a file with live data using your production Talent Apply IDs. Let your partnership manager know about the test, and this will start an internal review of the test file.
  5. Upon official approval from Talent.com of your initial test file, you can go live with the new functionality using your production API key.
  6. When switching to production, it is recommended to proceed with additional test file deliveries for definitive confirmation. This last step is optional.
API requirements
  • Upload format: .csv (preferred), .xml (for legacy integrations).
  • Upload size: Up to 1GB of data per upload. Please break larger files into multiple uploads.
  • Upload frequency: Maximum one upload per hour.
  • Columns:
    • apply_id - Talent.com's Apply ID. String, exactly 16 characters long.
    • disposition_timestamp - ISO-8601 format date and time when a disposition activity occurred. Time zone information is required.
    • status - Normalized disposition status, e.g. "HIRED". Check the Field Definitions section below.
See full code examples below to use the API.
Standard integration setup
To generate a disposition data file, ATS partners will need to create a scheduled task that runs periodically. The recommended period is one file generation per day.

A typical file example will include three headers:
  • disposition_timestamp,
  • apply_id,
  • status.
The following rules need to be followed when creating the file:
  • Each application state change should be represented in a row/record.
  • Do not include data from previous uploads.
  • Do not include duplicates of the same record if there was no change in the status. For example, NEW -> HIRED is valid, NEW -> NEW -> HIRED is not.
Note that a single apply-ID can have multiple events/records per report, as a single application may have multiple updates in a row per day. However, the same information must not be repeated whether it is in the same file or in different files.
Keep in mind that the CSV file should only include applications whose status has changed. Below are examples of correct and incorrect CSV file uploads for a specific set of application status changes.
Sample Correct CSV
Sample Correct XML (for legacy integrations only)
Correct
Day 1 - File 1
disposition_timestamp apply_id status
2022-01-01T01:00:00z appid001 NEW
Day 2 - File 2
disposition_timestamp apply_id status
2022-01-02T01:00:00z appid002 NEW
Day 3 - File 3
disposition_timestamp apply_id status
2022-01-03T01:00:00z appid001 CONTACTED
2022-01-03T01:00:00z appid003 NEW

This example is correct because the data was uploaded only when:


  • There were new applications.
  • There was a change on the apply_id status.
Incorrect
Day 1 - File 1
disposition_timestamp apply_id status
2022-01-01T01:00:00z appid001 NEW
Day 2 - File 2
disposition_timestamp apply_id status
2022-01-01T01:00:00z appid001 NEW
2022-01-02T01:00:00z appid002 NEW
Day 3 - File 3
disposition_timestamp apply_id status
2022-01-02T01:00:00z appid002 NEW
2022-01-03T01:00:00z appid001 CONTACTED
2022-01-03T01:00:00z appid003 NEW

This example is incorrect because:


  • "2022-01-01T01:00:00z, appid001, NEW" is duplicated, it should have only appeared on day 1.
  • "2022-01-02T01:00:00z, appid002, NEW" is duplicated, it should have only appeared on day 2.
Field definitions
Field
Required?
Description
apply_id Yes

The unique identifier for the job application that is used to reference the employer, candidate, job, and more.

This is the id field in the Talent Apply JSON application data.

See how the id field is referenced in this JSON application file example.

status Yes

IMPORTANT: Read this carefully.

Normalized application status. The Status field is used by Talent.com to determine what happens to applications when they are submitted to your ATS. There are 6 different statuses we look for (see below). You must categorize the statuses from your ATS with exactitude into the six categories. Without an accurate mapping, Talent.com cannot determine with reliability what happens to an application. If you have custom statuses in your ATS, please mention this to your Talent.com manager.


Talent.com Status Description
NEW The application arrived via Talent 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. Talent.com uses this as a signal to help determine employer responsiveness, which can affect the quality and volume of candidates an employer receives.

INTERVIEWED The job seeker has been interviewed.
OFFERED An offer of employment has been sent to the job seeker.
HIRED The job seeker accepted an offer of employment.
REJECTED A job seeker has been explicitly rejected or all remaining job seekers rejected after the role closed.

If you are unable to comply with this step, please contact your Talent.com manager.
disposition_timestamp Yes

ISO 8601 format timestamp with timezone information for when the status change occurred.

E.x. November 5, 1994 at 8:15 am Eastern Time would be: 1994-11-05T08:15:30-05:00

  • The separator between date and time must be a capital 'T'.
  • Time zone information is required.
  • Use the format+/-HH:MMfor time zone information, unless it is UTC (see next point).
  • For UTC, "+00:00", "Z", and "z" all valid, but "-00:00" is not valid.
  • Please use 00:00:00 for hour/minute/second if you do not have actual time information.
API instructions for exporting data to Talent.com
Integration
Our API allows your organization to programmatically deposit disposition information. Two steps are required for the integration:
  1. Obtain a presigned Amazon S3 URL by POST request to this API using the assigned API Key.
  2. Make a PUT request to upload the file to the URL returned in Step 1.

Note: To prevent uploading files with the same name, use a naming convention that allows you to distinguish your files from other files in your organization.

Obtaining a signed S3 URL
To receive the signed S3 bucket URL, create a POST request to our API with the file names you are uploading. A presigned upload URL will be returned for each file. See below for requirements and responses.
Required request headers
  • Content-Type: application/json
  • Accept: application/json
  • token: <YOUR API KEY>
Parameters
  • file_names
    • Type: JSON list of file names to get an upload URL.
    • Note: Please do not pass a file path here, only the file's name.
  • Accepted Extensions: csv, xml
Limitations
  • Files must not be larger than 1 GB.
  • The URL generated will expire in one hour.
  • All files must pass extension validation. Files with unsupported extensions will not upload.
Success response
A HTTP status of 200 and a JSON object/dictionary will be returned with keys as the file_names sent and values corresponding to the presigned S3 URL. See examples below for details.
Error response
A HTTP status non 200 and dictionary containing the key Error will be returned and give more information.
Uploading files
Once you have the presigned URL, upload files to the AWS Bucket using a PUT request. See below for an example, or refer to the official AWS documentation.
Curl Code example
Frequently asked questions
  • Should I send an empty file for periods that have no data?
    arrow
  • Can I send data in intervals of less than one hour?
    arrow
    No, you must aggregate your data before sending it. Please get in touch with your Talent.com manager if you are interested in making more frequent uploads.
  • My ATS supports custom statuses. How can I map them appropriately?
    arrow
    Please reach out to your Talent.com manager for assistance.
  • Why do I get a SignatureDoesNotMatch error when trying to upload a file to S3 using a pre-signed upload URL?
    arrow
    This is a problem with S3. Double-check the headers you are sending. Do not send a "Content-Type" header to S3. Please refer to S3 documentation if you cannot resolve this issue.
Need assistance?
Contact our integration support team at: integrations@talent.com if you need help.
Disclaimer
While our integration documentation is publicly available as reference material, it is intended to be implemented only by ATS partners who have signed a Master Services Agreement with Talent.com.

Terms of Service - Privacy Policy - Cookie Policy