Quickstart

The ZenHire API is one platform with four modules — CV DeepMatch, CV DeepSearch, Interview, and Speech — behind a single base URL and a single auth model. This page gets you from zero to your first call, then points you at the module you need.

Base URL: https://platform.zenhire.ai/api/v1

1. Get an API key

Create an API key in the ZenHire dashboard. Keys look like zh_api_… and every request sends it as an X-API-Key header. Each key is scoped to your client and to the modules your client has enabled.

See Authentication for rotation and per-module permissions.

2. Learn the shared model

Every module works the same way, so what you learn once applies everywhere:

• One auth header — X-API-Key on every request.
• Async submit → poll — you submit a job and get back an id, then poll GET …/{id} until it reaches a terminal status (success / partial / failed). An optional webhook_url can deliver the result instead of polling.
• Universal concepts — the id model, error envelope, credits, and health are identical across modules. Read them once in the Universal section.

3. Pick your module

Module	What it does	Start here
CV DeepMatch	Score a CV against a job description.	CV DeepMatch overview
CV DeepSearch	Search a corpus of parsed CVs for the best-matching candidates against a position.	CV DeepSearch overview
Interview	Run an AI voice interview and retrieve the recording + transcript.	Interview quickstart
Speech	Score interview audio for vocabulary, fluency, and accent (CEFR).	Speech overview

A first call (Speech example)

Here is the submit → poll shape end to end, using the Speech module. CV DeepMatch, CV DeepSearch, and Interview follow the same pattern against their own endpoints.

cURL

# Submit — returns an id
curl -X POST "https://platform.zenhire.ai/api/v1/speech/analyze" \
  -H "X-API-Key: zh_api_YOUR_KEY_HERE" \
  -F "audio=@interview.mp3" \
  -F "language=en"

# Poll — until status is success / partial / failed
curl "https://platform.zenhire.ai/api/v1/speech/analyze/req_1705412345678_abc123" \
  -H "X-API-Key: zh_api_YOUR_KEY_HERE"

Python

import requests

BASE = "https://platform.zenhire.ai/api/v1"
KEY  = "zh_api_YOUR_KEY_HERE"

# Submit — returns an id
with open("interview.mp3", "rb") as f:
    submit = requests.post(
        f"{BASE}/speech/analyze",
        headers={"X-API-Key": KEY},
        files={"audio": f},
        data={"language": "en"},
    ).json()

# Poll — until status is success / partial / failed
result = requests.get(
    f"{BASE}/speech/analyze/{submit['id']}",
    headers={"X-API-Key": KEY},
).json()
print(result)

Node.js

import fs from "node:fs";

const BASE = "https://platform.zenhire.ai/api/v1";
const KEY  = "zh_api_YOUR_KEY_HERE";

// Submit — returns an id
const form = new FormData();
form.append("audio", new Blob([fs.readFileSync("interview.mp3")]), "interview.mp3");
form.append("language", "en");
const submit = await (await fetch(`${BASE}/speech/analyze`, {
  method: "POST",
  headers: { "X-API-Key": KEY },
  body: form,
})).json();

// Poll — until status is success / partial / failed
const result = await (await fetch(`${BASE}/speech/analyze/${submit.id}`, {
  headers: { "X-API-Key": KEY },
})).json();
console.log(result);

The id is the run's canonical identifier and never expires — you can stop and resume polling later. Don't poll a given id faster than every 10 seconds.

Next steps

• Your first request — a complete, production-grade Speech integration (escalating poll, 429 handling, retries).
• Authentication — keys, rotation, permissions.
• Universal concepts — auth, ids, errors, credits, and health, shared by every module.
• Module references: CV DeepMatch · CV DeepSearch · Interview · Speech.