Skip to content

Zoho Recruit integration · Workflow webhook + API v2

Screen Zoho Recruit candidates with HireLayer

Zoho Recruit parses resumes and can call any URL from a workflow rule, so a new candidate can start your own screening service without a marketplace extension. HireLayer scores each candidate against the job opening with an explanation per criterion, and your service writes the score, a note, tags and normalized skills back through the Recruit API.

Trigger
Workflow rule with a webhook action
Zoho Recruit API
REST API v2, OAuth 2.0 Self Client
Write-back
Notes, tags, Skill_Set, Educational_Details
Cost
2 credits per candidate
Zoho Recruit + HireLayer
  1. 1A candidate is addedZoho RecruitA workflow rule on the Candidates module calls your webhook with the candidate’s record ID and a secret you chose.
  2. 2Parse the resumeHireLayerYour service lists the candidate’s attachments, downloads the latest with /Candidates/{id}/Attachments/{attachment_id} and sends it to HireLayer Resume Scorer, which parses it first.
  3. 3Score against the job openingHireLayerThe service finds the associated opening with /Candidates/{id}/associate, and Resume Scorer scores the resume against that opening’s criteria.
  4. 4Write back to Zoho RecruitZoho RecruitA note with the score and the gaps, a tag for strong matches, and normalized skills in Skill_Set.

What teams do with HireLayer and Zoho Recruit

  • Screen new applicants

    Every candidate associated with an opening gets a score and the list of mandatory criteria met, in a note your recruiters read on the recrod.

  • Rank an opening’s pipeline

    List the candidates of a job opening with GET /Job_Openings/{id}/associate, send their IDs to HireLayer Resume Scorer with precise_ranking on, and note each candidate’s rank and ranking reason.

  • Normalized skills

    Write HireLayer’s normalized skills to Skill_Set, so a search in Recruit finds the same skill under one nane across candidates.

  • Complete manual records

    Candidates added by hand or through Insert Records may have empty education and experiance tables. Fill Educational_Details and Experience_Details from HireLayer’s parse.

Connect Zoho Recruit to HireLayer

This is a small service you run, for example a serverless function or an n8n workflow. Webhooks and workflow rules are configured in Zoho Recruit Setup; no marketplace extension is needed.

  1. 1

    Register an API client

    In the Zoho API Console (api-console.zoho.com), create a Self Client with scopes such as ZohoRecruit.modules.ALL and ZohoRecruit.modules.attachments.all, plus ZohoRECRUIT.settings.tags.ALL for tags. Use the accounts server and API domain of your data center, for example zohoapis.eu for an EU account. Access tokens last one hour.

  2. 2

    Create the webhook

    In Setup → Automation → Actions → Webhooks, add your URL with the POST method, the candidate’s record ID as a parameter, and a secret as a custom parameter that your service checks.

  3. 3

    Add a workflow rule

    In Setup → Automation → Workflow rules, create a rule on Candidates that runs when a record is created, and add the webhook as an instant action. A Blueprint transition can call the same webhook.

  4. 4

    Extract criteria, parse, score and write back

    Send each job opening’s description once to HireLayer Job Criteria Extractor with the opening ID as job_id: HireLayer stores it with its criteria, for free. For each call, download the latest attachment, send it to Resume Scorer, which parses and scores it against the associated opening in one call, then post a note and add a tag.

Where HireLayer results go in Zoho Recruit

Fields are written by API name. Check yours in Setup → Developer Space → APIs → API Names, especially for custom fields and the Experience_Details subfields. Resume Scorer keeps the parsed resume: read its fields for free with GET /api/v4/resumes/{application_id}.

HireLayer fieldZoho Recruit API v2Note
score + summary + criteria[]POST /recruit/v2/Notes (Note_Title, Note_Content, Parent_Id, se_module)What recruiters read
score ≥ your thresholdPOST /Candidates/{id}/actions/add_tags?tag_names=…
scoreCustom field by API name (PUT /Candidates/{id})Create the field first
resume.skills[].skill_titleSkill_Set (comma-separated text)Merge with the current value
resume.info_candidate.job_titleCurrent_Job_Title
resume.educations[]Educational_Details (Institute_School, Degree, Duration.from/to)
resume.work_experiences[]Experience_DetailsSubfield API names from the fields metadata

A webhook handler in TypeScript

A minimal Node.js handler: it checks the secret, finds the associated job opening, downloads the latest attachment, parses and scores it in one Resume Scorer call, then adds a note and a tag. Add your own token refresh and retries.

zoho-recruit-webhook.tstypescript
const HIRELAYER = 'https://hirelayer.co'
const headers = { 'X-API-Key': process.env.HIRELAYER_API_KEY! }
// API domain of your data center, e.g. https://www.zohoapis.eu for EU accounts
const RECRUIT = `${process.env.ZOHO_API_DOMAIN}/recruit/v2`
type Attachment = { id: string; File_Name: string; Created_Time: string }

const json = { 'Content-Type': 'application/json' }
const zoho = async (path: string, init: RequestInit = {}) => fetch(`${RECRUIT}/${path}`, {
  ...init, headers: { ...json, Authorization: `Zoho-oauthtoken ${await zohoAccessToken()}` },
})
// Zoho answers 204 with no body when a list is empty
const list = (path: string) =>
  zoho(path).then((r) => (r.status === 204 ? [] : r.json().then((body) => body.data)))

// params: the parameters configured on the Zoho Recruit webhook
export async function handle(params: { candidate_id: string; secret: string }) {
  if (params.secret !== process.env.ZOHO_WEBHOOK_SECRET) return 401
  const id = params.candidate_id

  // 1. The job opening and the latest attachment of the candidate
  const [opening] = await list(`Candidates/${id}/associate`)
  const [latest] = (await list(`Candidates/${id}/Attachments`)).sort(
    (a: Attachment, b: Attachment) => b.Created_Time.localeCompare(a.Created_Time))
  if (!opening || !latest) return 200

  // 2. Download, then parse and score in one call (about a minute), against
  // the opening stored with its criteria by POST /api/v4/jobs/extract-criteria
  const form = new FormData()
  form.append('request', JSON.stringify({
    job: { job_id: opening.id },
    resumes: [{ file: 'resume', application_id: id }],
  }))
  form.append('resume', await zoho(`Candidates/${id}/Attachments/${latest.id}`)
    .then((r) => r.blob()), latest.File_Name)
  const response = await fetch(`${HIRELAYER}/api/v4/resumes/score`, {
    method: 'POST', headers, body: form, signal: AbortSignal.timeout(150_000),
  })
  // Errors come as { error: { code, message } } (no credits, unknown job): skip.
  if (!response.ok) return 200
  const { scores: [result] } = await response.json()
  // An unreadable file fails only its own score, unbilled.
  if (result.evaluation_status !== 'completed') return 200

  // 3. Note and tag on the candidate
  await zoho('Notes', { method: 'POST', body: JSON.stringify({ data: [{
    Note_Title: 'HireLayer screening',
    Note_Content: `Score: ${Math.round(result.score * 100)}/100\n${result.summary}`,
    Parent_Id: id,
    se_module: 'Candidates',
  }] }) })
  if (result.score >= 0.7) {
    await zoho(`Candidates/${id}/actions/add_tags?tag_names=HireLayer%20strong%20match`, { method: 'POST' })
  }
  return 200
}

Good to know

  • Webhook limits

    Zoho documents daily webhook limits per edition: 10,000 calls or 100 per user license on Professional, 20,000 or 200 per license on Enterprise, whichever is lower. POST payloads are capped at 10,000 characters, and Notes cannot trigger webhooks.

  • API credits

    Each API call uses credits from a rolling 24-hour pool, for example 10,000 plus 500 per license on Professional, up to 500,000. The handler above makes up to five Zoho calls per candidate, plus token refreshes.

  • Zoho Recruit already parses resumes

    Its parser fills names, contact details, skills, education and experience, with a configurable Parser Mapping. Use HireLayer for job-specific scores and normalized skills, and only fill tables Recruit left empty.

  • Not a Marketplace extension

    HireLayer is not listed on Zoho Marketplace. You connect it with your own API client and workflow webhook; Zoho documents webhook limits for the Professional and Enterprise editions, so check that your edition includes webhooks.

HireLayer and Zoho Recruit: questions

Does HireLayer integrate with Zoho Recruit?

Yes, through a workflow-rule webhook and the Zoho Recruit API v2: your service receives each new candidate, sends the resume to HireLayer, and writes the score back as a note and tags. HireLayer has no extension on Zoho Marketplace.

Can I screen Zoho Recruit candidates with AI?

Yes. HireLayer turns the job opening into weighted criteria, then scores each candidate from 0 to 1 with an explanation per criterion, written in the job opening’s language. The score supports your recruiters’ review; it does not change candidate statuses.

Can I use Make instead of code?

Yes. Zoho Recruit has a Make app maintained by Make that adds Make an API Call, which can reach the attachments endpoint. Call HireLayer with Make’s HTTP module.

Which Zoho data center should I use?

The one your Recruit account lives in: API calls go to zohoapis.com, zohoapis.eu, zohoapis.in, zohoapis.com.au, zohoapis.com.cn or zohoapis.jp, with the matching accounts server. Use the API domain returned during authorization. HireLayer itself processes data in the EU.

Does Zoho Recruit already parse resumes?

Yes, with a built-in parser and a configurable Parser Mapping, including for files sent to POST /Candidates/actions/import_document. HireLayer adds what the parse does not: a score against each job opening, with the criteria met and missing.

Connect Zoho Recruit to HireLayer today

The Free plan includes 50 credits a month, no card required. Parsing a resume costs one credit, scoring one per resume evaluated, and extracting job criteria is free.