Bullhorn ATS

​

Implementation Overview

Implementation Type: Kombo-based Integration
Note Format: HTML
Status: Production Ready

​

Configuration

​

Feature Summary

All core ATS features are supported through Kombo’s unified API with extensive custom implementations for Bullhorn-specific functionality.

​

Bullhorn-Specific Features

​

Custom Field Querying

When fetching jobs, we automatically query 64 custom fields from Bullhorn:

• Custom Date Fields: customDate1 through customDate3 (3 fields)
• Custom Float Fields: customFloat1 through customFloat3 (3 fields)
• Custom Integer Fields: customInt1 through customInt8 (8 fields)
• Custom Text Fields: customText1 through customText40 (40 fields)
• Custom Text Block Fields: customTextBlock1 through customTextBlock5 (5 fields)

This ensures we capture all possible custom data configured in any Bullhorn instance.

​

Note Action Types

We use custom action types when adding notes to candidates and applications. Bullhorn restricts action names to 30 characters:

• TZ - Call Summary - General call summaries
• TZ - Call Summary - Passed - Successful screenings
• TZ - Call Summary - Failed - Failed screenings
• TZ - Inbound SMS - Incoming text messages
• TZ - Outbound SMS - Outgoing text messages
• TZ - Inbound Email - Incoming emails
• TZ - Outbound Email - Outgoing emails
• Tenzo:Not Interested - Candidate declined
• TZ - Note - Generic notes

Meeting Copilot summaries use a note action that reflects the meeting type, so each meeting type is distinguishable in Bullhorn:

• TZ - Job Order Form - Intake (hiring-manager) meeting summaries
• TZ - Interview Summary - Candidate interview summaries
• TZ - Sales Summary - Sales meeting summaries
• TZ - Discovery Summary - Staffing discovery meeting summaries
• TZ - Meeting Summary - Other / untyped meetings

Each of these labels is overridable per org via the Bullhorn note-action-labels dynamic config; the values above are the defaults. Customer Bullhorn instances that validate Note.action must provision all five meeting-summary labels (Job Order Form, Interview Summary, Sales Summary, Discovery Summary, and Meeting Summary) or posts for those meeting types will land under unrecognised action strings.

​

Placements

Custom implementation for Bullhorn placement records:

• Stream placements with pagination
• Track placement dates (dateAdded, dateBegin, dateLastModified)
• Parse placement status and candidate/job associations
• Filter by dateLastModified for incremental syncing (so dateBegin edits are picked up)

​

Tearsheets (Hotlists)

Support for Bullhorn tearsheet functionality:

• Stream tearsheets with pagination
• Handle large tearsheets (500+ candidates/jobs per tearsheet)
• Retrieve candidate and job IDs from tearsheets
• Filter deleted tearsheets always; filter private tearsheets by default (configurable via Tearsheet sync scope in Admin → ATS Integrations → Configuration → Sync Settings)
• Optionally filter by tearsheet name using a configured regular expression (Tearsheet name pattern)

​

Job Creation

Custom implementation for creating jobs in Bullhorn:

• Create JobOrder entities via passthrough API
• Support for custom field values on job creation
• Returns Bullhorn job ID for immediate use

​

Implementation Notes

​

Custom Data Models

• BullhornJob: Extended job model with custom field values (includes all 64 custom fields)
• BullhornCandidate: Candidate model with category, owner, status metadata
• BullhornPlacement: Placement records with submission tracking, dates, and status
• BullhornTearsheet: Tearsheet linking candidates to jobs with pagination support

​

Field Type Mappings

Bullhorn field types are mapped to generic types via BULLHORN_FIELD_MAPPINGS:

• BigDecimal → float
• Integer → integer
• String → string
• Timestamp → date
• Boolean → boolean

​

Candidate Field Updates

We can update both standard fields and custom fields on candidates:

• Standard fields: Updated via POST /entity/Candidate/{id} with automatic type conversion
• Custom fields: Updated via custom field update endpoints with schema validation

​

Job Caching

Job data is cached in-memory to avoid repeated API calls when processing multiple applications for the same job. Cache can be cleared with clear_caches() method.

​

Pagination Limits

Bullhorn has a maximum record request count of 500 records per request (BULLHORN_RECORD_REQUEST_COUNT_MAX). All streaming operations handle this automatically with proper pagination.

​

Tearsheet sync (Service Bus queue)

When USE_SERVICE_BUS_TEARSHEET_SYNC is enabled (Bullhorn integrations only):

1. Publish phase (ATS sync cron): streams tearsheets modified since tearsheets_last_synced_at, resolves campaigns per linked JobOrder (prefers SOURCING for legacy dual-campaign jobs, else MAIN), and publishes one Service Bus message per (campaign_id, Kombo candidate_id) pair.
2. Worker (tearsheet-sync topic / sync_consumer or ats_tearsheet_sync_worker): processes receive batches like applicant/candidate sync — skips pairs that already have CCI, batch-indexes candidates that need it, then add_to_campaign with source TEARSHEETS (CCI re-check before add to avoid duplicate ATS applications).

Azure topic requirements:

• Sessions required on the topic and worker subscription (session_id = integration id).
• If the topic is partitioning-enabled with duplicate detection, each message sets:
  • message_id = {integration_id}:{campaign_id}:{ats_candidate_id} (stable pair key)
  • partition_key = integration id (must match session_id)
• Azure duplicate detection suppresses accidental double-publishes of the same pair within the topic window; workers also skip pairs already on the campaign via CCI.
• Workers skip pairs already on the campaign (get_already_synced_ats_candidate_ids); tearsheets_last_synced_at advances after a successful publish, not after workers finish.

JobDiva hotlist sync remains in-memory and is not queued in this phase.

​

Related Files

• Implementation: server/ats/bullhorn_ats_client.py
• Tearsheet queue: server/ats/service_bus/tearsheet_sync_service_bus.py, bullhorn_tearsheet_sync_stream.py, tearsheet_sync_worker_service.py
• Field Mappings: server/ats/field_type_mapper.py (BULLHORN_FIELD_MAPPINGS)
• Base Class: server/ats/base_kombo_ats_client.py

​

See Also

• ATS Coverage Matrix