UKG Ready ATS

Implementation Overview

Implementation Type: Kombo-based Integration
Note Format: Plain Text
Status: In Development UKG Ready integrates through Kombo’s unified API, layered with native UKG Ready REST calls via Kombo passthrough. Kombo’s unified data alone cannot deliver phone numbers, job custom fields, applicant custom-field writeback, or applicant-visible notes, so those paths call the native /ta/rest/v2/companies/{company_reference}/... API directly.

Configuration

Property	Value	Description
Provider Enum	`ukgready`	Identifier in ProviderEnum
Note Format	`PLAIN`	Plain-text notes
Disposition Reasons	Not Supported	Rejection handled via stage movement
Note Targets	Application only	Candidate notes not supported
Passthrough URL	`/passthrough/ukgready/api`	Kombo passthrough endpoint
Company Reference	`ukg_ready_company_reference`	Required org config; company id or short name used in every native API path

Without ukg_ready_company_reference, all native paths silently degrade: no phone numbers, job custom fields never reach the enhanced job cache (so the rules schema stays empty even though schema discovery itself reads the cache without native calls), and custom-field/note writebacks raise errors. Configure it before enabling the integration.

Setup

Kombo Connection Registration

Create the Kombo connection link from Tenzo, so Kombo receives the Tenzo org ID as End user origin ID. If the integration is connected directly in Kombo without it, the integration_created webhook carries no org ID and Tenzo never auto-creates the ats_integrations row. Recovery: reconnect through a Tenzo-generated link, or manually replay the integration_created webhook with the Tenzo org ID.

Company Reference

Native paths are /ta/rest/v2/companies/{company_reference}/.... UKG accepts either the numeric company ID or a short-name reference in !short_name format (the Kombo sandbox uses !kombo). Validate the value with a native GET after configuring — a wrong reference fails with Company not found, it is not arbitrary. If the short name does not work for a tenant, use its numeric UKG company ID.

Customer-Side Field Setup (“Tenzo Active”)

The customer creates a UKG Ready job requisition custom field and sets it on the jobs Tenzo should process. Sandbox-proven gotcha (verified by live A/B toggle): with “Display to Applicant” unchecked, UKG strips both custom_field_configs and custom_fields from the requisition API response while the job itself remains visible — making a hidden field indistinguishable from a nonexistent one. The checkbox must be enabled for Tenzo to read the field at all. No workaround through the Kombo passthrough endpoint is currently confirmed; customers who do not want the field applicant-visible need Kombo or UKG to confirm whether a privileged internal-requisition endpoint exists.

Stage IDs

Capture real stage IDs from synced job payloads after connection (prefer job-specific stage IDs). Stage movement through Kombo is the disposition mechanism, so Copper State’s routing stages (Application Received, above/below-threshold, Tenzo Recruiter Review) must be mapped before go-live.

Feature Coverage

Streaming Operations

Stream Jobs (Inherited)
Stream Applications (Inherited)
Stream Candidates (Inherited + native phone enrichment in batches of 8)

Kombo does not return UKG phone numbers, so candidate streaming backfills phones from the native applicant endpoint.

Application Management

Move to Stage (Inherited)
Get Disposition Reasons — returns an empty list
Reject Applications (Single & Bulk) — no-op with logging; use stage movement to disposition
Create Applications (Inherited, candidate phone-enriched first)
Get All Stages (Inherited)

Job Management

Get Job by ID (Inherited)
Get Enhanced Job — Kombo job + native requisition detail (custom_field_configs and custom_fields mapped to custom_field_values)
Batch Job Fetch — follows Kombo cursors until the requested limit, then enriches each job through native passthrough with bounded concurrency (8)

Job custom-field values feed the rules engine (e.g. “Tenzo Active” filtering).

Candidate Management

Get Candidate by ID (Inherited + phone enrichment)
Get Candidate by Remote ID (Inherited + phone enrichment)
Find by Details (Inherited)
Get Resume (Inherited)

Notes & Attachments

Add Note to Application — writes to the Job Application applicant_comment via native passthrough (GET existing → append → PUT). Kombo’s generic note action targets company_comment, which recruiters do not read in the customer’s workflow. Sandbox-verified for post-interview summaries and SMS/email activity notes.
Add Note to Candidate — Not Supported (no-op)
Attachment upload — Inherited via Kombo and sandbox-verified, but UKG lists uploaded application attachments on the candidate document list, not on the application.
Attachment readback — GET application attachments is not supported for UKG Ready (Kombo returns INTEGRATION.ACTION_NOT_AVAILABLE); candidate attachment fetching is limited to CV/resume-style documents.

Resume Ingestion

Only files uploaded through UKG’s dedicated resume source come back through Kombo as type CV and feed automatic resume ingestion. PDFs added via UKG’s Supporting Documents modal surface as attachment type OTHER and are not picked up as resumes.

Custom Fields

Job Custom Fields — read-only; schema inferred from custom_field_values on jobs already in the enhanced job cache (open and closed, capped at 10,000, memoized per client instance) — no native calls at schema-discovery time. A field is only discoverable once it has a non-empty value on at least one synced job. UKG INT strings are normalized to integers during job enrichment; other values are inferred as boolean, integer, or string from their cached value. Writeback is impossible: requisitions are GET-only in the UKG REST API, so the Tenzo job link field stays disabled (DisabledTenzoJobLinkCustomField).
Applicant Custom Fields — writable; index-based array on the applicant record. Powers application score, candidate score, interview link, and completion rate writebacks.
Application Custom Fields — UKG job applications have no custom fields; application-level writes route to the underlying applicant (same pattern as Breezy and RecruitCRM).

Native Enrichment

Kombo’s unified payloads for UKG Ready are missing two things Tenzo depends on: job custom fields and candidate phone numbers. Both are backfilled from the native API during sync.

Job Custom Fields → Rules Engine (“Tenzo Active”)

Kombo’s unified job payload does not carry UKG custom fields, so during job sync each Kombo job is enhanced with a native requisition fetch (GET /recruitment/job-requisitions/{remote_id}, bounded at 8 concurrent). UKG returns field definitions and values as two separate arrays matched by index:

{
  "custom_field_configs": [
    { "index": 0, "label": "Tenzo Active", "type": "CHAR" }
  ],
  "custom_fields": [
    { "index": 0, "value": "Yes" }
  ]
}

The client joins them by index into custom_field_values on UkgReadyJob, which lands in the enhanced job cache — the layer the rules engine filters on. That is the full path that makes “Tenzo Active” job filtering work; without the native fetch, the field never reaches rules. Batch fetches follow Kombo cursors until the requested limit, so large requisition counts are not truncated at one page. Rules-schema discovery is decoupled from this: it reads custom_field_values straight from the enhanced job cache (see Custom Fields above) and issues no native or Kombo calls of its own. The native requisition fetch happens only during job sync, when the cache is populated.

Candidate Phone Numbers

Kombo returns no phone numbers for UKG Ready candidates, so every candidate read path — streaming, get-by-ID, get-by-remote-ID, and the pre-flight of create-application — backfills phones from the native applicant endpoint (GET /applicants/{remote_id}) whenever Kombo left phone_numbers empty. During candidate streaming this runs in batches of 8. Ordering honors phones.preferred_phone (see Implementation Notes for its dual label/number semantics), so the number the candidate prefers is the one dialed first.

Applicant Custom-Field Writeback

Four post-interview writebacks target applicant custom fields, each driven by its own org-config setting (an applicant field index picked on the ATS integration settings page):

Writeback	Config storage key
Application score	`application_score_custom_field`
Candidate score	`candidate_score_custom_field`
Interview link	`interview_link_custom_field`
Completion rate	`completion_rate_custom_field`

Configure each to a distinct index (see Duplicate Field Indexes below). The write path is a native read-modify-write:

GET the applicant (/applicants/{id})
Merge updates into applicant_custom_fields by index
PUT the applicant back

Requirements proven against the UKG sandbox:

The PUT payload must echo the applicant’s account and address blocks or UKG rejects the request with validation errors.
applicant_custom_fields is index-based ([{"index": 0, "value": "..."}]) — the REST API exposes no labels, so the settings UI offers 50 index placeholders (“Applicant Custom Field N”).
Configured field IDs accept several formats: "3", "custom_field_3", "applicant_custom_fields.3", "applicant_custom_fields[3]".
UKG can return HTTP 200 with a nested error envelope; responses are checked for errors / user_messages with severity ERROR and raised as AtsApiError.

Implementation Notes

Applicant Fields Are Person-Level

Applicant custom fields belong to the person, not the application. A candidate with two concurrent applications shares one set of score/link/completion fields — last write wins. The per-application source of truth is the applicant_comment note.

Non-Atomic Writebacks

Both the custom-field writeback and the note append are GET → merge → PUT sequences that re-send the full array/comment. Concurrent writers from different processes can silently overwrite each other. Within one call’s post-processing, writes are sequential, so this only matters cross-process.

`preferred_phone` Dual Semantics

The native applicant phones.preferred_phone field holds either a phone-type label ("CELL", "HOME", …) or the raw preferred number itself. The client handles both: a raw number is emitted first; a label reorders the typed phone fields.

Closed Jobs Disappear

UKG Ready only returns publicly visible jobs. Closed jobs vanish from the API entirely (and filled jobs look open until closed), so missing-job warnings are suppressed for disabled positions (expected stale-cache behavior, not an integration error).

No Job Code

Kombo returns job_code as null for UKG Ready jobs. Shared naming code falls back to remote_id where a requisition/job code is needed.

Field Type Mapping

UKG custom-field config types map via UKG_READY_FIELD_MAPPINGS: CHAR → string, INT → integer, BOOL/BOOLEAN → boolean.

Duplicate Field Indexes

If two writeback configs resolve to the same applicant field index (e.g. custom_field_3 and 3), a warning is logged and their writes will overwrite each other. Configure each writeback to a distinct index.

Implementation: server/ats/ukg_ready/ukg_ready_ats_client.py
Models: server/ats/ukg_ready/ukg_ready_models.py
Config: UkgReadyConfig in server/ats/config/providers.py
Field Mappings: UKG_READY_FIELD_MAPPINGS in server/ats/field_type_mapper.py
Base Class: server/ats/base_kombo_ats_client.py
Tests: server/tests/unit/ats/ukg_ready/

Internal Documentation

Modules

Fraud Risk

Outreach

ATS Implementations

Implementation Overview

Configuration

Setup

Kombo Connection Registration

Company Reference

Customer-Side Field Setup (“Tenzo Active”)

Stage IDs

Feature Coverage

Native Enrichment

Job Custom Fields → Rules Engine (“Tenzo Active”)

Candidate Phone Numbers

Applicant Custom-Field Writeback

Implementation Notes

Applicant Fields Are Person-Level

Non-Atomic Writebacks

`preferred_phone` Dual Semantics

Closed Jobs Disappear

No Job Code

Field Type Mapping

Duplicate Field Indexes

See Also

​Implementation Overview

​Configuration

​Setup

​Kombo Connection Registration

​Company Reference

​Customer-Side Field Setup (“Tenzo Active”)

​Stage IDs

​Feature Coverage

​Native Enrichment

​Job Custom Fields → Rules Engine (“Tenzo Active”)

​Candidate Phone Numbers

​Applicant Custom-Field Writeback

​Implementation Notes

​Applicant Fields Are Person-Level

​Non-Atomic Writebacks

​preferred_phone Dual Semantics

​Closed Jobs Disappear

​No Job Code

​Field Type Mapping

​Duplicate Field Indexes

​Related Files

​See Also

Implementation Overview

Configuration

Setup

Kombo Connection Registration

Company Reference

Customer-Side Field Setup (“Tenzo Active”)

Stage IDs

Feature Coverage

Native Enrichment

Job Custom Fields → Rules Engine (“Tenzo Active”)

Candidate Phone Numbers

Applicant Custom-Field Writeback

Implementation Notes

Applicant Fields Are Person-Level

Non-Atomic Writebacks

`preferred_phone` Dual Semantics

Closed Jobs Disappear

No Job Code

Field Type Mapping

Duplicate Field Indexes

Related Files

See Also