Zoho Recruit API: Free to Call, Paid to Be Notified
An application can reach the inbox before Zoho Recruit is allowed to fire a webhook. Carly can respond there, update the candidate record, coordinate the interview, chase hiring-manager feedback, and keep the recruiter briefed. That inbox-first path works on every plan; higher tiers can also start configured workflows directly from Zoho Recruit events.
Zoho Recruit gives you the API on every plan, including Free — 5,000 API credits a day at no cost. Registering a client takes two minutes at api-console.zoho.com and requires no approval.
What it doesn’t give you on Free or Standard is any way to find out something happened. Webhooks are gated to Professional and above. So the cheap plans get full read and write access and no event triggers at all, which means polling — and polling spends the credits you were given instead of the notifications you weren’t.
That’s the shape of this API, and it’s worth understanding before you design anything.
What recruiters actually automate with it
What’s realistic depends heavily on your plan, because the API and the notifications are priced separately.
On Professional or Enterprise, where webhooks work, you can react as things happen:
- New applications acknowledged immediately rather than whenever someone opens the module.
- Stage changes that notify the hiring manager without a status email someone has to write.
- Interview scheduling and reminders to both sides, plus the debrief chase afterward.
On Free or Standard, nothing gets pushed to you, so the same jobs run on a schedule instead — checking every few minutes rather than reacting instantly. For most recruiting workflows that difference is tolerable; for high-volume application handling it isn’t.
Either way, your inbox is often the faster trigger. Applications and candidate replies land in email regardless of plan, and acting on the email sidesteps the tier question entirely.
Getting credentials
Go to https://api-console.zoho.com, pick a client type, and click Create. You get a Client ID and Client Secret immediately.
Five client types exist, and the useful one for automation is Self Client — meant for back-end jobs with no manual intervention, and it requires no Homepage URL, no Redirect URI, and no JS domains. For the browser-based types, Zoho’s docs note you can use dummy values if you don’t have a real domain.
Token lifetimes: the grant token is valid for one minute and single-use, the refresh token never expires, and you can mint at most 5 refresh tokens per minute.
The data center trap is worse than it sounds
Zoho runs regional data centers, and getting this wrong produces the least helpful error in the API.
Every regional host resolves and returns an identical 401 AUTHENTICATION_FAILURE — recruit.zoho.com, .eu, .in, .com.au, .jp, and the rest. A nonexistent module on the correct host returns the same 401. So a wrong-region call is indistinguishable from a bad token, with no 404 to hint at the real problem.
The reason is buried in Zoho’s own error documentation: each data center issues a different client secret for the same registered client. Copy your US secret into a European deployment and you get invalid_client with nothing indicating that secrets are region-scoped.
Two fixes: enable Multi-DC on the client, or generate the grant, access, and refresh tokens all from one domain. And use the api_domain value returned in the token response rather than hardcoding a host.
One documentation bug worth knowing, because Zoho made it themselves: their multi-DC page lists the API base as www.zohoapis.com. That’s Zoho CRM’s host and it does not serve Recruit — a call to zohoapis.com/recruit/v2/Candidates returns a 404. The correct base is:
https://recruit.zoho.com/recruit/v2/Current version is v2. Both v1 and v3 return 404.
Credits, not calls
Zoho meters an org-wide daily credit budget on a rolling 24-hour window:
| Edition | Daily credits | Ceiling |
|---|---|---|
| Free | 5,000 | 5,000 |
| Standard | 5,000 + (users × 250) | 100,000 |
| Professional | 10,000 + (users × 500) | 500,000 |
| Enterprise | 15,000 + (users × 1,000) | 1,000,000 |
Credits are weighted, and the weights matter more than the totals. Most calls cost 1. But:
- Fetching records with a
cvid(custom view) costs 3 - Insert and update cost 1 credit per 10 records, up to 100 records per call
- Bulk Read Initialize costs 50
- Bulk Write Initialize costs 500 — that’s 10% of a Free org’s entire daily budget in a single call
So the obvious pagination pattern, reading through a custom view, is three times the cost of the naive one.
Concurrency is a separate limit — 5 simultaneous calls on Free, 10 on Standard, 15 on Professional, 20 on Enterprise, per user per app. Zoho is explicit that there are no per-minute restrictions: you can make as many calls a minute as you like provided concurrency stays within bounds. A sub-limit of 10 applies on top for custom-view reads, sorted reads, and multi-record writes.
One caveat on the table above: Zoho’s pricing page now shows three tiers (Free, Standard, Enterprise) while its developer docs still describe four including Professional. The credit numbers are current; whether Professional is still purchasable for new customers is unclear.
Full CRUD, with names that lie
Standard modules — Candidates, Job Openings, Contacts, Clients, Interviews, Assessments, Notes, Tasks, Events — support create, read, update, upsert, delete, and search.
Rather than assuming coverage, introspect it. The modules response carries per-module booleans: creatable, editable, deletable, viewable, and critically api_supported. Zoho ships modules the API can’t touch, and that flag flips on their schedule.
Module API names aren’t the labels. Job Openings is Job_Openings — but its internal module_name is Potentials, inherited from Zoho CRM. Code keyed on internal names breaks in confusing ways, and default modules’ API names can’t be renamed.
Batch limits are 100 records per insert or update call, 500 per tag call, with separate async Bulk Read and Bulk Write APIs for anything larger.
Webhooks cost a tier jump
Zoho’s own plan comparison is unambiguous: webhooks are not available on Free or Standard. Professional gets 10,000 calls a day, Enterprise 20,000.
And webhooks here don’t fire on their own — they must be attached to a workflow rule, which supplies the trigger condition (record created, or record meeting criteria). Workflow rules themselves need Standard or above, and time-based actions and field updates are also Professional-only.
Setup is Setup → Automation → Actions → Webhooks → Configure Webhook. Supported on Candidates, Contacts, Job Openings and other core modules plus Events and Tasks. Call Logs and Notes are not supported.
The constraints are tight enough to design around:
- POST and GET only, and ports 80 and 443 only
- Maximum 10 Recruit fields per webhook payload
- Maximum 6 webhooks per workflow rule — one instant plus five time-based
- Daily caps are the lower of the flat number or a per-user allowance
- Extra webhook calls are a paid add-on
That 10-field cap is a real design constraint, not a footnote. The payload is a thin notification rather than a full record, so you will nearly always call back into the API to get the rest — which spends credits. The event and the data are billed separately, in effect.
Zia is real, and not in the API
Zoho’s AI, Zia, does genuine work in Recruit: matching candidates to job openings with ranked scores, assigning skill proficiency from resume phrasing (distinguishing “very strong in Java” from “basic knowledge”), tracking experience recency, and classifying how rare a skill is against your applicant pool.
Two things to be clear about. Plan gating is murky — Zia appears nowhere in Zoho’s feature comparison matrix, while the pricing page implies AI candidate matching is an Enterprise addition. Adjacent features are gated more clearly: semantic search is Professional and up, and resume parsing is capped at 250 a day on Standard and 500 on Professional.
And there’s no Zia API. No AI endpoints appear anywhere in the v2 documentation tree. Zia is a UI feature; you can read the scores it produces on records, but you can’t invoke it.
Getting the event to do something
If you’re on Professional or Enterprise, you have workflow-triggered webhooks with a 10-field payload. If you’re on Free or Standard, you have polling and a credit budget.
Either way, the assistant side hits the same wall.
These assistants can run on a schedule now — ChatGPT Scheduled Tasks and Claude Cowork both do unattended work on a timer. What none of them do is fire on an event: nothing starts because a record changed, a message landed, or a deadline passed. The schedule is the trigger, and the gap between "every hour" and "the moment it happens" is where the work falls through.
“Summarize this month’s pipeline by job opening” is well within what ChatGPT or Claude will do with a Zoho Recruit export. “Message the candidate and notify the hiring manager the moment a submission lands” is not, because nothing on that side is watching for it.
Carly is the half that watches. Three ways to run Recruit work through it, in the order that matters:
- From the event — on Professional or Enterprise, point a Zoho Recruit workflow webhook at a Carly workflow. A submission lands and the whole response runs: fetch the fields Zoho’s 10-field payload left out, notify the hiring manager, prepare the candidate message, log the result. This is the half neither ChatGPT nor Claude has.
- From your inbox, on any plan — applications and candidate replies arrive by email whether or not you pay for webhooks, and Carly triggers on the email. That sidesteps the tier question entirely, which is worth knowing before you upgrade for notifications alone.
- On a schedule — on Free and Standard, a recurring sweep for new or changed records. Use ordinary record reads rather than three-credit custom-view reads, and pick a cadence that fits the 5,000-credit budget.
Candidate messages and stage changes should follow the recruiting team’s templates, permissions, and review rules; connecting the API doesn’t activate them automatically.
Because Zoho Recruit exposes an OAuth API, you can connect it natively to Carly from the Integrations tab. Carly can then use Recruit in on-demand, recurring, and event-triggered workflows alongside the rest of the Zoho and business apps you connect. AI agents start at $35/month, and workflow steps that don’t use AI run free.
Frequently Asked Questions
Is the Zoho Recruit API available on the free plan?
Yes. Free gets 5,000 API credits per day and 5 concurrent calls. Registering a client at the Zoho API Console requires no approval or paid plan. What Free doesn’t get is webhooks.
Which Zoho Recruit plan includes webhooks?
Professional and above. Professional allows 10,000 webhook calls a day, Enterprise 20,000. Free and Standard have no webhook access, so change detection means polling. Webhooks also have to be attached to a workflow rule rather than firing independently.
What is the Zoho Recruit API base URL?
https://recruit.zoho.com/recruit/v2/. Note that Zoho’s own multi-DC documentation lists www.zohoapis.com, which is Zoho CRM’s host and returns a 404 for Recruit endpoints.
How do Zoho Recruit API credits work?
Credits are consumed per call, weighted by operation. Most calls cost 1 credit; fetching records with a custom view costs 3; inserts and updates cost 1 per 10 records; Bulk Read Initialize costs 50 and Bulk Write Initialize costs 500. The budget is per organization on a rolling 24-hour window.
Why do my Zoho Recruit API calls return 401 even with a valid token?
Most likely a data center mismatch. Every regional host returns an identical 401, and each data center issues a different client secret for the same client. Enable Multi-DC on the client, or generate all tokens from a single domain, and use the api_domain returned in the token response.
Can I access Zia through the Zoho Recruit API?
No. Zia’s candidate matching, skill proficiency scoring, and resume parsing are UI features with no documented API endpoints. You can read resulting scores on records but can’t invoke Zia programmatically.
More: Best AI workflow automation tools · Best AI agents for productivity · AI agents for HR and people ops
Ready to automate your busywork?
Carly schedules, researches, and briefs you—so you can focus on what matters.
See what people say
"Before Carly, I relied on a Calendly link, but the whole process felt impersonal and not very professional. Carly changed that by handling all the back-and-forth, so I'm no longer stuck in endless email threads trying to line up schedules.
Now Carly reaches out to candidates, shares my real-time availability, lets them pick a slot, then sends a Zoom link and drops it straight into my calendar. She sends reminders to both of us before each call, which has significantly reduced no-shows and last-minute confusion.
On top of scheduling, Carly acts like a full executive assistant, sending me my schedule the night before so I can prepare for each call. It reminds me of the old x.ai assistant, but Carly is noticeably smarter, faster, and better suited to my healthcare recruitment business."
