zohorecruit

# Zoho Recruit Access the Zoho Recruit API with managed OAuth authentication. Manage candidates, job openings, interviews, applications, and recruitment workflows with full CRUD operations. ## Quick Start ```bash # List all candidates python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates?per_page=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/zoho-recruit/{native-api-path} ``` Replace `{native-api-path}` with the actual Zoho Recruit API endpoint path. The gateway proxies requests to `recruit.zoho.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Zoho Recruit OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-recruit&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'zoho-recruit'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "0c9fa9b1-80b6-4caa-afc2-8629fe4d9661", "status": "ACTIVE", "creation_time": "2026-02-06T07:48:59.474215Z", "last_updated_time": "2026-02-06T07:57:52.950167Z", "url": "https://connect.maton.ai/?session_token=...", "app": "zoho-recruit", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Zoho Recruit connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '0c9fa9b1-80b6-4caa-afc2-8629fe4d9661') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Modules #### List All Modules Get a list of all available modules in your Zoho Recruit account. ```bash GET /zoho-recruit/recruit/v2/settings/modules ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/settings/modules') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Candidates #### List Candidates ```bash GET /zoho-recruit/recruit/v2/Candidates ``` **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `fields` | string | - | Comma-separated field API names | | `sort_order` | string | - | `asc` or `desc` | | `sort_by` | string | - | Field API name to sort by | | `converted` | string | - | `true`, `false`, or `both` | | `approved` | string | - | `true`, `false`, or `both` | | `page` | integer | 1 | Page number | | `per_page` | integer | 200 | Records per page (max 200) | **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates?per_page=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "data": [ { "id": "846336000000552208", "First_Name": "Christina", "Last_Name": "Palaskas", "Email": "c.palaskas@example.com", "Candidate_Status": "Converted - Employee", "Current_Employer": "Chandlers", "Current_Job_Title": "Technical Consultant", "Experience_in_Years": 3, "Skill_Set": "Communication, Presentation, Customer service", "Candidate_Owner": { "name": "Byungkyu Park", "id": "846336000000549541" } } ], "info": { "per_page": 10, "count": 1, "page": 1, "more_records": false } } ``` #### Get Candidate by ID ```bash GET /zoho-recruit/recruit/v2/Candidates/{record_id} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates/846336000000552208') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Search Candidates ```bash GET /zoho-recruit/recruit/v2/Candidates/search?criteria={criteria} ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `criteria` | string | Search criteria (e.g., `(Last_Name:contains:Smith)`) | | `email` | string | Search by email | | `phone` | string | Search by phone | | `word` | string | Global word search | | `page` | integer | Page number | | `per_page` | integer | Records per page | **Search Operators:** - Text: `equals`, `not_equal`, `starts_with`, `ends_with`, `contains`, `not_contains`, `in` - Date/Number: `equals`, `not_equal`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `between` **Example:** ```bash python <<'EOF' import urllib.request, os, json import urllib.parse criteria = urllib.parse.quote('(Candidate_Status:equals:Active)') req = urllib.request.Request(f'https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates/search?criteria={criteria}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Create Candidate ```bash POST /zoho-recruit/recruit/v2/Candidates Content-Type: application/json { "data": [ { "First_Name": "John", "Last_Name": "Doe", "Email": "john.doe@example.com", "Phone": "555-123-4567", "Current_Job_Title": "Software Engineer" } ] } ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "data": [{ "First_Name": "John", "Last_Name": "Doe", "Email": "john.doe@example.com", "Phone": "555-123-4567" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "data": [ { "code": "SUCCESS", "status": "success", "message": "record added", "details": { "id": "846336000000600001", "Created_Time": "2026-02-06T10:00:00-08:00",