Connect Zoho Recruit

Prelim runs an AI phone screen on every candidate the moment they hit your trigger stage. Results push back to the candidate as a note plus custom fields, and high scorers auto-advance to your next stage. Multi-DC: works for US, EU, IN, AU, JP, CA, SA, UK, and CN.

Setup is five steps. About ten minutes end to end. You only do steps 1, 3, and 4 once per Recruit org.

Pro plan or higher required

ATS integrations are gated to Prelim Pro+. If you're on the free or small tier, upgrade from Settings → Billing first.

1. Install the Prelim extension

Install the Prelim extension from the Zoho Marketplace (or via the private install URL if you're part of the pre-launch cohort). The extension adds a Send to Prelim button to your Candidate Record Details page so a recruiter can manually fire a screen from inside Recruit when they need to. It also reads your per-org Prelim API key from extension settings so the button can talk to Prelim.

Marketplace listing / private install link: coming with the public Marketplace launch. If you're testing during early access, ping marcus@prelim.chat for the private install URL.

2. Connect from the Prelim dashboard

Go to Settings → Integrations in Prelim and find the Zoho Recruit ATS tile. Click Connect with Zoho Recruit. You'll be redirected to Zoho to authorize Prelim.

After consent, you land back on the integrations page with Connected shown next to the tile. Prelim mints two things at that point:

A unique webhook URL (one per organization)
A shared secret slot for X-Prelim-Token so we can verify incoming webhooks

Both are displayed on the same settings page once connected. Step 4 is where you wire them into Recruit.

Multi-DC works automatically

Prelim detects your Recruit data center from the OAuth callback (US, EU, IN, AU, JP, CA, SA, UK, CN) and stores it on your integration row. You don't pick a region anywhere.

3. Create the custom fields in Recruit

Once per Recruit org. Prelim writes screen results into four custom fields on the Candidate record so recruiters can see them inline. Add them under Setup → Customization → Modules and Fields → Candidates:

Prelim Screen Status - Picklist: Not Started, Sent, In Progress, Completed, No Response
Prelim Score - Decimal (5,2)
Prelim Transcript URL - URL
Prelim Completed At - Date/Time

Field API names must match exactly

Case-sensitive, underscores between words. Use Prelim_Screen_Status, Prelim_Score, Prelim_Transcript_URL, and Prelim_Completed_At. Recruit auto-derives the API name from the display label, but verify in the field config before saving. Once created they cannot be renamed.

4. Configure the workflow webhook

This is what fires the Prelim screen automatically when a candidate hits your chosen stage. Two parts: create the webhook (a), then bind it to a workflow rule (b).

(a) Create the webhook

In Recruit: Setup → Automation → Actions → Webhooks → New Webhook. Set:

URL to Notify: the webhook URL from the Prelim integration settings page (copy from the connected tile)
Method: POST
Body format: JSON
Custom Headers: add X-Prelim-Token = the webhook secret from Prelim (the same value you set in the "Webhook shared secret" field on the Prelim integration tile)
Body template: paste the JSON below

json

{
  "candidate_id": "${Candidates.Candidate Id}",
  "job_id": "${Candidates.Associated Job Id}",
  "application_id": "${Applications.Application Id}",
  "candidate_email": "${Candidates.Email}",
  "candidate_name": "${Candidates.First Name} ${Candidates.Last Name}",
  "candidate_phone": "${Candidates.Phone}",
  "stage_name": "${Applications.Application Status}"
}

Why a shared secret?

Recruit's workflow webhooks don't natively sign payloads. The X-Prelim-Token header is how Prelim verifies the request really came from your Recruit org and not someone who guessed the URL. Use 32+ random characters.

(b) Bind it to a workflow rule

Setup → Automation → Workflow Rules → Create Rule on the Applications module:

Trigger: when Application Status equals Phone Screen (or whatever stage you pick - this is what you also paste into "Trigger stage" on the Prelim tile)
Instant Action: select the webhook from step 4a

Save the rule. From this point forward, every Application moving into your trigger stage fires a Prelim screen.

5. Test end-to-end

Move a test candidate's application into the trigger stage. Within a few seconds you should see:

An email arrive in the candidate's inbox with their Prelim screen link
The candidate appear under Candidates in Prelim

After the candidate completes the screen, the same Recruit candidate record will show:

A Note on the candidate feed with score, recommendation, and summary
The four Prelim_* custom fields populated
An attached Prelim_Transcript_URL link to the full conversation in Prelim
If you set an advance-stage and the score is above your threshold, the application auto-moves to the next stage

Troubleshooting

Webhook returns 401 Unauthorized

Means the X-Prelim-Token custom header on your Recruit webhook doesn't match the "Webhook shared secret" on the Prelim tile. Update one side to match. The comparison is exact and case-sensitive.

Webhook returns 404 Not Found

The webhook URL doesn't resolve to a Prelim integration. Re-copy the URL from Settings → Integrations - the per-org token is the last path segment and changes if you disconnect + reconnect.

Webhook fires but no screen appears

Two common causes:
(1) Your "Trigger stage" on the Prelim tile doesn't exactly match the Recruit Application Status that fired. Whitespace and casing count (well, casing doesn't - the compare is case-insensitive - but whitespace does).
(2) The candidate has no email on the Recruit record. The webhook body needs candidate_email populated. Check the Candidate record in Recruit.

Score doesn't auto-advance the candidate

Check three things on the Prelim tile:
(1) "Advance to stage on qualifying score" is set to a stage name that exists in the relevant Recruit hiring pipeline
(2) "Score threshold" is set (default is 7.0)
(3) The candidate's screen score is at or above that threshold (check the screen detail in Prelim)

Custom fields are empty on the candidate

The field API names must match exactly: Prelim_Screen_Status, Prelim_Score, Prelim_Transcript_URL, Prelim_Completed_At. Recruit silently ignores writes to misnamed fields. Open Setup → Customization → Modules and Fields → Candidates and verify each API name.

Disconnecting

Click Disconnect on the Prelim Zoho Recruit tile to revoke the connection. Your Recruit data isn't touched - existing notes, custom field values, and attachments stay where they are. Only the live wiring is removed.

If you also want to stop the webhook from firing on the Recruit side, delete the workflow rule under Setup → Automation → Workflow Rules. Otherwise the rule will keep firing the webhook and Prelim will reject with a 404 until you reconnect.