Disposition API Guide

Overview

The Disposition API allows job advertisers to communicate applicant disposition data back to Talroo. This includes status updates throughout the hiring process such as interviews, offers, rejections, and hires.

Why Send Disposition Data?

Sharing disposition data provides significant benefits:

• Improved Job Performance: Jobs with disposition data receive better visibility and more qualified candidates
• Enhanced Matching: Understanding hiring outcomes helps Talroo's candidate-job matching AI improve your candidate quality
• Campaign Optimization: Disposition data enables better budget allocation and bid optimization
• Recruitment Insights: Track hiring funnel performance and identify bottlenecks in your process

Data Flow

1. Job Seeker Applies: Candidate applies through Talroo to your job posting
2. Tracking Begins: Talroo provides a tlr_sid, or tlr_application_id ID value that is unique to the job click or application generated by the candidate
3. Status Updates: As candidates progress through your hiring process, send disposition events back to Talroo
4. Optimization: Talroo uses this data to improve job visibility and candidate quality

Technical Details

Full Disposition API schema can be found here

API Endpoint

POST https://api.talroo.com/disposition/v1/events

Send one or more disposition events in a single API call.

Authentication

There is no authentication needed to use the disposition endpoint.

Request Format

The API accepts either a single event object or an array of event objects in the body of the POST request.

Example: Single Event

{
  "tlr_sid": "9dc3d611-e014-4ddb-a87f-d36e3e10a813",
  "event": "application_completed",
  "raw_event": "new application",
  "event_time": "2024-02-25T12:56:33Z"
}

Example: Multiple Events

[
  {
    "tlr_sid": "9dc3d611-e014-4ddb-a87f-d36e3e10a813",
    "event": "application_completed",
    "raw_event": "new application",
    "event_time": "2024-02-25T12:56:33Z"
  },
  {
    "tlr_application_id": "ba0fbcff-1488-11f0-9d88-121fb3094105",
    "event": "rejected",
    "reason": "uncertified",
    "meta_data": {
      "detail_reason": "Candidate did not have the required certification"
    },
    "event_time": "2024-03-21T19:23:00-05:00"
  }
]

caution

The Disposition API supports a maximum of 100 events in a single API call.

Required Fields

Identifier (one required):

• tlr_sid: Click ID provided by Talroo
• tlr_application_id: Application ID provided by Talroo

Event Details:

• event: The disposition event type (see supported events below)
• event_time: ISO8601 timestamp when the event occurred

info

The event_time should be the time the event occurred, and NOT the time the events are to sent Talroo.

Optional Fields:

• reason: Only supported for the rejected events (see supported reasons below)
• raw_event: Your internal event name (max 128 characters)

Supported Event Types

Application Events:

• registration - Candidate registered/created profile
• lead - Initial interest expressed
• application_started - Application process begun
• application_completed - Application submitted
• application_qualified - Application meets requirements
• application_unqualified - Application doesn't meet requirements
• application_withdrawn - Candidate withdrew application

Hiring Process Events:

• contacted - Initial contact made with candidate
• screening - Phone/initial screening completed
• assessment - Skills assessment completed
• interview_scheduled - Interview scheduled
• interviewed - Interview completed
• background_check - Background check initiated/completed
• offered - Job offer extended
• offer_declined - Candidate declined offer
• hired - Candidate hired
• rejected - Application rejected
• onboarded - Employee onboarding completed
• other - Custom event type

Rejection Reasons

When using event: "rejected", include a reason field:

• failed_checks - Failed background/reference checks
• unresponsive - Candidate didn't respond to communications
• uncertified - Lacks required certifications/qualifications
• out_of_area - Location not suitable
• job_closed - Position no longer available
• hired_different_role - Hired for different position
• other - Other reason

Example Request

curl --location 'https://api.talroo.com/disposition/v1/events' \
--header 'Content-Type: application/json' \
--data '[
  {
    "tlr_sid": "9e9ee8f1-6cb3-4195-93ff-78678cbde550",
    "event": "screening",
    "raw_event": "phone_screened",
    "event_time": "2024-04-07T15:18:00-05:00"
  },
  {
    "tlr_sid": "9e9ee8f1-6cb3-4195-93ff-78678cbde550",
    "event": "interviewed",
    "raw_event": "completed_interview",
    "event_time": "2024-04-07T15:19:00-05:00"
  },
  {
    "tlr_application_id": "15c4dce613e511f0837b0e09a3d063d115c4dce613e511f0837b0e09a3d063d1",
    "event": "rejected",
    "reason": "job_closed",
    "event_time": "2024-04-07T15:20:00-05:00"
  }
]'

API Responses

Success Responses

Single Event Success (200 OK):

{
  "success": true
}

Multiple Events Success (200 OK):

{
  "num_succeeded_events": 10
}

Error Responses

Single Event Validation Error (400 Bad Request):

{
  "message": "Validation failed",
  "tlr_sid": "9dc3d611-e014-4ddb-a87f-d36e3e10a813",
  "errors": [
    {
      "message": "This value should not be null.",
      "field": "event",
      "value": null
    }
  ]
}

Multiple Events Partial Failure (400 Bad Request):

{
  "num_succeeded_events": 8,
  "failed_events": [
    {
      "message": "Validation failed",
      "tlr_sid": "9dc3d611-e014-4ddb-a87f-d36e3e10a813",
      "errors": [
        {
          "message": "This value should not be null.",
          "field": "event",
          "value": null
        }
      ]
    }
  ]
}

Server Error (500 Internal Server Error):

{
  "message": "Internal server error"
}

Best Practices

Timing

• Send disposition events as soon as they occur in your system
• For batch processing, send events as frequently as possible, and at the very least daily
• Include accurate event_time timestamps, not when the API call is made

tip

Sending disposition events in as close to real time as possible will provide the best traffic optimization results.

Data Quality

• Always use the exact tlr_sid or tlr_application_id provided by Talroo
• Send events in chronological order when possible

Error Handling

• Implement retry logic for temporary failures (500 errors)
• Log failed events for manual review and reprocessing
• Monitor your success rates and investigate patterns in failed events

Integration Tips

• Test with single events first, then implement batch processing
• Use your ATS webhooks or scheduled jobs to trigger API calls