Skip to main content

​
Implementation overview

Implementation type: Direct API integration Authentication: TempWorks personal access token Note format: Plain text TempWorks currently has one production configuration for Surge and a standard TempWorks Cloud flow under development for Employnet. Both use TempWorksAtsClient, but they intentionally enter different synchronization paths.
The Surge extension is operational. The TEN-934 standard job, application, stage-catalog, and candidacy-writeback code is implemented, but it must remain disabled until the target tenant’s credentials and read contracts are validated.

​
Operating modes

The standard flow does not enable candidate sync. A candidate is read in the context of a Job Order Candidate application rather than by sweeping the full employee directory.

​
Connection configuration

TEN-934 adds these values to each TempWorks integration:
  • API base URL;
  • Account SID; and
  • write-only Auth Token.
The client resolves these values through org_config.config, the existing per-integration typed configuration accessor. Missing values fail closed for every TempWorks integration. Surge uses the same per-integration configuration and has no environment-variable fallback.

​
Current verified coverage

​
Surge extension

  • Incremental employee/candidate streaming into one configured Tenzo job
  • Employee detail and resume retrieval
  • Employee notes and attachments
  • Employee interest-code and hire-status operations
  • Assignment caching and Surge placement communication behavior
  • Job Order detail lookup for assignment and placement workflows
All assignment and placement orchestration is Surge-specific. Both entry points must guard on the stable Surge organization UUID, not a display name or the presence of generic TempWorks configuration.

​
Standard TempWorks flow

TEN-934 now provides:
  • Job Order streaming and detail reads;
  • Job Order Candidate syncing through TempWorks’ candidate search endpoint, with individual applications loaded from the Job Order Candidate details endpoint. Tenzo stores both IDs as job_order_id:job_order_candidate_id so it can find the same application again;
  • dynamic Job Order Candidate status retrieval as application stages;
  • active Employee and Job Order custom-field definition reads, plus Job Order custom-field value reads; and
  • Employee creation for sourced or uploaded candidates using the candidate’s state and target Job Order’s branch, application creation, status writeback to the exact candidacy, Employee and Job Order custom-field writeback, and validated basic Job Order PATCH support, with request failures propagated.
The read paths have been verified against Surge production with bounded GET requests, including all 21 configured candidate statuses, 35 active Employee custom fields, 21 active Job Order custom fields, and 20 custom-field values on a sampled Job Order. No live candidacy status write has been made. Employnet validation remains pending its tenant credentials, so its job and applicant sync must remain disabled. TEN-934 phase one covers:
  • Job Orders as Tenzo jobs;
  • Job Order Candidates as Tenzo applications;
  • reversible application identity containing both Job Order ID and Job Order Candidate ID;
  • Job Order Candidate statuses as application stages;
  • active Employee and Job Order custom-field reads; and
  • Employee and application creation for sourced or uploaded candidates, status writeback to the exact candidacy, Employee custom-field writeback after an interview, and Job Order writeback for the Tenzo Job Link.
Employee creation calls the documented POST /Employees endpoint only when the target Job Order has a branch ID and the Tenzo candidate has a state that can be sent as the required TempWorks region. Missing required data fails closed before any TempWorks write. After TempWorks returns the Employee ID, Tenzo attempts to read the Employee back and uses the existing Job Order Candidate creation path. If that immediate read is delayed, Tenzo retains the validated ID from the create response so a retry does not create a duplicate Employee. The basic Job Order PATCH implementation accepts only field paths explicitly documented by TempWorks and sends replace operations through the shared ATS request transport. TEN-934 does not expose the full set of operational Job Order fields in the provider field picker; choosing which fields users may edit remains separate product scope.

​
Initial rollout state

Provision a standard TempWorks Cloud integration with job, applicant, and candidate sync disabled. Enable job sync only after the tenant’s authentication, Job Order search metadata, hierarchy scope, and a bounded job page are verified. Enable applicant sync only after jobs, candidacy identity, status mapping, and a bounded candidacy page are verified. Candidate sync remains disabled unless full employee-directory sync is separately approved.

​
Interview summaries, PDFs, and custom fields

The TempWorks Swagger reference and public OpenAPI description do not expose application-scoped notes, documents, or custom data as resources equivalent to the Employee and Job Order resources:
  • PUT /JobOrders/{id}/candidates/{jobOrderCandidateId} exposes one nullable, overwriteable comment, not an append-only message or note resource.
  • No /JobOrders/{id}/candidates/{jobOrderCandidateId}/documents resource is documented. TempWorks documents uploads to other entities, including the Employee document upload.
  • No /JobOrders/{id}/candidates/{jobOrderCandidateId}/CustomData resource is documented. The public contract exposes CustomData for Employees and Job Orders instead.
TempWorks does not provide append-only notes or documents on a Job Order Candidate. When the corresponding writebacks are enabled, Tenzo writes the full interview summary to the associated Employee’s message history using the tenant’s configured Message Action and uploads the interview PDF to that Employee’s document history. This keeps the complete results available without overwriting the candidacy’s limited comment field. Because both are stored on the Employee, recruiters can see them across that person’s candidacies. The TempWorks service representative must have access to the configured Message Action and Employee document type. If either is missing or not permitted, Tenzo leaves the affected result in Tenzo and propagates the failed TempWorks write through post-processing retries. A write that continues to fail ultimately dead-letters for investigation instead of being silently logged and dropped. Application custom fields remain disabled until TempWorks exposes an approved application-scoped contract.

​
Other unsupported operations

  • Rejecting with a separate disposition reason
  • Re-engagement automation
  • Employnet assignment or placement automation
  • server/ats/tempworks/tempworks_ats_client.py
  • server/ats/tempworks/tempworks_library.py
  • server/ats/tempworks/tempworks_models.py
  • server/ats/candidate_sync_controller.py
  • server/ats/config/providers.py
  • server/ats/config/models.py
  • server/ats/org_config.py

​
See also