# integrating-zoho-recruit

> Manages integration with Zoho Recruit API v2. Use when the user needs to fetch candidates, job openings, handle OAuth authentication, or sync data with Zoho Recruit.

- Author: ROVR Outsourcing
- Repository: edzelubalde-rovr/rovr-recruit-backend
- Version: 20260209120717
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/edzelubalde-rovr/rovr-recruit-backend
- Web: https://mule.run/skillshub/@@edzelubalde-rovr/rovr-recruit-backend~integrating-zoho-recruit:20260209120717

---

---
name: integrating-zoho-recruit
description: Manages integration with Zoho Recruit API v2. Use when the user needs to fetch candidates, job openings, handle OAuth authentication, or sync data with Zoho Recruit.
---

# Integrating Zoho Recruit

## When to use this skill
- The user wants to connect to Zoho Recruit.
- The user asks to "fetch candidates" or "sync jobs" from Zoho.
- The user needs help with Zoho OAuth (Client ID, Secret, Refresh Tokens).
- Debugging Zoho API errors (e.g., 401 Unauthorized, INVALID_TOKEN).

## Workflow
- [ ] **Credentials Check**: Ensure `ZOOHO_CLIENT_ID`, `ZOOHO_CLIENT_SECRET`, and `ZOOHO_REDIRECT_URI` are available (in `.env`).
- [ ] **Token Generation**:
    - [ ] Generate Grant Token from browser.
    - [ ] Exchange for Access/Refresh Tokens via curl/postman.
- [ ] **Module Identification**: Confirm which modules (Candidates, JobOpenings) are needed.
- [ ] **Implementation**: Create service/client class for API calls.
- [ ] **Token Refresh Strategy**: Implement middleware to refresh access token on 401.

## Instructions

### Authentication (OAuth 2.0)
Zoho Recruit uses OAuth 2.0. The flow:
1.  **Authorization Request**: User approves app -> get `code`.
    - URL: `https://accounts.zoho.com/oauth/v2/auth?scope=ZohoRecruit.modules.ALL&client_id=...&response_type=code`
2.  **Get Tokens**: Exchange `code` for `access_token` and `refresh_token`.
    - POST `https://accounts.zoho.com/oauth/v2/token`
3.  **Refresh Access Token**: Use `refresh_token` to get new `access_token` (expires in 1hr).

### API Basics
- **Base URL**: `https://recruit.zoho.com/recruit/v2` (or `.eu`, `.in`, etc. depending on DC).
- **Headers**:
    - `Authorization: Zoho-oauthtoken <ACCESS_TOKEN>`
    - `Content-Type: application/json`
- **Common Endpoints**:
    - `GET /Candidates`: List candidates.
    - `GET /JobOpenings`: List jobs.
    - `GET /settings/modules`: List available modules.
- **Search**: `GET /Candidates/search?criteria=(Email:starts_with:alice@)`

### Data Structure
- Records are wrapped in a `data` array: `{ "data": [ { ... } ], "info": { ... } }`.
- API Names (e.g., `First_Name`, `Email`) must be used, not display labels.

### Code Pattern (Node.js Example)
```javascript
async function fetchCandidates(accessToken) {
  const response = await fetch('https://recruit.zoho.com/recruit/v2/Candidates', {
    headers: { 'Authorization': `Zoho-oauthtoken ${accessToken}` }
  });
  if (!response.ok) throw new Error(`Zoho Error: ${response.status}`);
  const json = await response.json();
  return json.data;
}
```

## Resources
- [Zoho Recruit API v2 Docs](https://www.zoho.com/recruit/api-new/)
- [Zoho Creator API v2.1 (Reference)](https://www.zoho.com/creator/help/api/v2.1/)