Partner API Reference

Integrate Coco HR's AI-powered job assessments into your own ATS, HR platform, or recruiting workflow.

The Coco HR Partner API lets you create AI-generated assessments, invite candidates, and pull back scored evaluation reports — all from your own systems, with no SDK and no front-end work. Candidates take the test in any modern desktop browser at a link you receive from the API.

• API base URL: https://hr.cocolevio.com/api
• Interactive docs (ReDoc): https://hr.cocolevio.com/developers
• OpenAPI spec: https://hr.cocolevio.com/partner-api/openapi.json

Every path below is relative to the API base and lives under /apikey/. For example, POST /apikey/prepare_assessment is https://hr.cocolevio.com/api/apikey/prepare_assessment.

---

When to use the Partner API

Use it when you want to embed Coco HR assessments inside your own product or process:

• Trigger an AI-generated assessment when a candidate reaches a stage in your ATS.
• Email or SMS candidates a unique assessment link from your own system.
• Pull scored reports (per-question scoring, recordings, anti-cheat signals) back into your dashboard, CRM, or data warehouse.
• Parse resumes for contact details or skills before creating a candidate.

If you only need to run assessments occasionally, you can do everything from the Coco HR dashboard instead — the API is for automation and system-to-system integration.

---

Authentication

Every partner request must include this header:

Authorization: ApiKey <your-api-key>

The key represents your company (tenant). Treat it like a password — anyone holding it can create assessments and read candidate reports on your behalf. Do not embed it in client-side code, mobile apps, or public repositories; call the API from your backend.

Obtaining a key

Choose either method:

1. Dashboard (recommended). Sign in as a Company Admin, then go to API Management → Generate New Key (also reachable via Settings → API Keys).
2. Endpoint (browser session). While logged in to the dashboard, call GET /apikey/fetch-api-key to retrieve your existing key, or GET /apikey/generate-api-key to mint a new one.

Important: generate-api-key and fetch-api-key authenticate with your logged-in browser session, not the Authorization: ApiKey header. They are the only two endpoints that work this way — every other endpoint requires the header.

Rotating a key

Generating a new key replaces the old one. There is no separate revoke step: to invalidate a compromised key, generate a fresh one and update your integrations. Roll out the new key to your clients before rotating, since the old key stops working immediately.

---

Core concepts

A Coco HR assessment stitches together three records. The API can create all three in a single call (prepare_assessment), or you can manage each one individually.

Question types

Answer modes (assessment_type)

AI scores the free-form answers and surfaces them in the report alongside anti-cheat signals (tab-switch count, fullscreen status, etc.). See How AI scoring works and Anti-cheat and proctoring.

Your IDs vs Coco IDs

You pass your own integer identifiers — p_candidate_id, p_job_id (and job_id) — and Coco HR stores them alongside its internal IDs. Every partner endpoint accepts the IDs you originally sent, so you never have to store Coco's internal IDs.

• Reuse the same p_candidate_id across process_candidate and get_candidate_report.
• Reuse the same p_job_id / job_id across prepare_assessment, process_candidate, and update_assessment.
• job_id, p_job_id, and p_candidate_id must be integers.

---

The recommended end-to-end flow

sequenceDiagram
    participant You as Your system
    participant Coco as Coco HR API
    participant Cand as Candidate (browser)

    You->>Coco: GET /apikey/get_technologies (optional)
    Coco-->>You: skill catalogue
    You->>Coco: POST /apikey/prepare_assessment
    Coco-->>You: assessment_id + generated question titles
    You->>Coco: POST /apikey/process_candidate
    Coco-->>You: unique assessment_link
    You->>Cand: send assessment_link (email / SMS / your UI)
    Cand->>Coco: opens link, takes assessment in browser
    You->>Coco: GET /apikey/get_candidate_report/{p_candidate_id}
    Coco-->>You: verdict, per-question scoring, videos, anti-cheat

1. (Optional) List supported skills — GET /apikey/get_technologies. Pick exact skill names the AI generator recognises.
2. Create the assessment — POST /apikey/prepare_assessment creates the job, template, and AI theory questions in one call. Returns assessment_id and the generated question titles.
3. Add a candidate — POST /apikey/process_candidate returns a unique assessment_link.
4. Candidate takes the test — they open assessment_link in any modern desktop browser. No SDK or app required.
5. Fetch the report — GET /apikey/get_candidate_report/{p_candidate_id} returns status, per-question scoring, video URLs, and anti-cheat telemetry once the candidate finishes.

For finer control, manage jobs, templates, and questions individually (see the Advanced flow).

---

Endpoint reference

All endpoints are under /apikey/ and require the Authorization: ApiKey header unless noted.

Key management

These two use your logged-in browser session, not the ApiKey header.

Assessments

Applicants & reports

Jobs

Templates

Questions

Skills & question library

Resume parsing

---

Sample requests

Replace $KEY with your API key in the examples below.

Create an assessment

prepare_assessment creates the job, template, and AI theory questions in a single call. It consumes 1 assessment token. If an assessment already exists for the supplied job_id, it returns 400 — use update_assessment instead.

curl -X POST https://hr.cocolevio.com/api/apikey/prepare_assessment \
  -H "Authorization: ApiKey $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "12345",
    "job_title": "Senior Python Developer",
    "no_of_theory_questions": 5,
    "time_allowed_for_each_question": 10,
    "is_coding_challenge_required": "no",
    "coding_challenge_data": [],
    "assessment_type": "both",
    "required_skills": ["Python", "FastAPI", "AWS"]
  }'

Response:

{
  "message": "Assessment created successfully",
  "assessment_id": 1024,
  "questions": [
    {"id": 51, "queTitle": "Explain the difference between == and is in Python."},
    {"id": 52, "queTitle": "What is the purpose of async/await?"}
  ]
}

To include coding challenges, set "is_coding_challenge_required": "yes" and pass coding_challenge_data, e.g. [{"skill": "Python", "count": 2}].

Add a candidate

curl -X POST https://hr.cocolevio.com/api/apikey/process_candidate \
  -H "Authorization: ApiKey $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "p_candidate_id": "88012",
    "candidate_name": "Asha Verma",
    "candidate_email": "asha@example.com",
    "p_job_id": "12345",
    "candidate_phone": "+91-9000000000"
  }'

Response:

{
  "message": "Candidate processed successfully",
  "assessment_link": "https://hr.cocolevio.com/assessment/57291"
}

Share assessment_link with the candidate. The link is bound to that specific candidate and cannot be reused by anyone else. Registering the same email twice against the same p_job_id returns 400.

Fetch a candidate report

curl -X GET https://hr.cocolevio.com/api/apikey/get_candidate_report/88012 \
  -H "Authorization: ApiKey $KEY"

Poll periodically until assessment_status is Completed. Abridged response:

{
  "id": 88012,
  "name": "Asha Verma",
  "jobPostId": 12345,
  "email": "asha@example.com",
  "assessment_status": "Completed",
  "assessment_result": [
    {
      "question_id": 51,
      "question": "Explain how you would design a scalable caching layer...",
      "answer": "I would use Redis for in-memory caching with a TTL-based eviction policy...",
      "score": 8.5,
      "max_score": 10,
      "feedback": "Strong understanding of Redis and distributed caching...",
      "dimensions": {"Technical Depth": 8, "Communication": 9, "Problem-solving": 8}
    }
  ],
  "assessment_anti_cheat_data": {
    "browser": "Chrome",
    "device_type": "desktop",
    "device_used": "Windows",
    "webrtc_location": "Bangalore, Karnataka, India",
    "isvpn": false,
    "istabchange": true,
    "isfullscreen": true,
    "iscursormoved": true,
    "isAudioEnabled": true,
    "isVideoEnabled": false,
    "snaps": 3,
    "time_taken_for_assessment": "23"
  },
  "assessment_video": [
    {"que_no": "1", "file_type": "webm", "public_url": "https://s3.../1964_q1_answer.webm"}
  ]
}

assessment_result and assessment_video are only populated once the candidate finishes. For how scores are produced and what they mean, see How AI scoring works. For anti-cheat fields, see Anti-cheat and proctoring.

List the skill catalogue

curl -X GET https://hr.cocolevio.com/api/apikey/get_technologies \
  -H "Authorization: ApiKey $KEY"

[
  {"name": "Python", "uuid": "a1b2c3d4-...", "cmetadata": {"category": "Backend"}},
  {"name": "React", "uuid": "e5f6g7h8-...", "cmetadata": {"category": "Frontend"}}
]

Pass any returned name verbatim in required_skills (for prepare_assessment) or selected_technologies (for p-generate-questions). Names not in the catalogue still work but produce lower-quality AI questions.

Extract contact details from a resume

Fast heuristic extraction — no AI, no tokens.

curl -X POST https://hr.cocolevio.com/api/apikey/p-parse-resume-contact \
  -H "Authorization: ApiKey $KEY" \
  -F "file=@/path/to/resume.pdf"

{"name": "Archit Saki", "email": "itsarchit.saki@gmail.com", "phone": "7448251252"}

AI resume parsing (skills & experience)

Consumes 1 resume token. Send as multipart/form-data with file, job_requirement, and skill_set.

curl -X POST https://hr.cocolevio.com/api/apikey/p-resume-parsing \
  -H "Authorization: ApiKey $KEY" \
  -F "file=@/path/to/resume.pdf" \
  -F "job_requirement=Software Engineer with 3+ years of experience" \
  -F "skill_set=Python, Django, AWS"

{
  "message": "Resume Parsed successfully",
  "resume_parsed_data": {
    "match_skill_sets": ["Python", "FastAPI", "AWS"],
    "total_experience": 5,
    "current_location": "Bangalore",
    "graduation_yes_no": true,
    "highest_qualification": "B.Tech in Computer Science"
  }
}

---

Advanced: manual job, template, and question management

prepare_assessment is the quickest path, but you can also build assessments piece by piece — useful when you want to reuse a template across jobs, control the exact question structure, or build a custom question library.

1. Create a job (only title required)

curl -X POST https://hr.cocolevio.com/api/apikey/p-create-job \
  -H "Authorization: ApiKey $KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Senior Python Developer", "description": "We are hiring...", "location": "Remote"}'

2. Create a reusable template

curl -X POST https://hr.cocolevio.com/api/apikey/p-create-template \
  -H "Authorization: ApiKey $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Developer Assessment",
    "time_allowed_for_each_question": 10,
    "assessment_type": "both",
    "no_of_questions": 5,
    "is_coding_required": "no"
  }'

3. Add a custom question

curl -X POST https://hr.cocolevio.com/api/apikey/p-create-question \
  -H "Authorization: ApiKey $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 456,
    "queTitle": "Explain the difference between == and is in Python",
    "queType": "theory"
  }'

queType accepts theory or coding.

---

Public application form

Every API-created job also has a shareable public URL:

https://hr.cocolevio.com/job/<job_id>

Candidates can apply themselves (resume upload, no pre-registration). Applicants who arrive this way appear in GET /apikey/p_get_applicants — you don't need to call process_candidate for them.

---

Token metering

Partner usage is metered in two token types:

p-parse-resume-contact consumes no tokens (it uses heuristic text parsing, not AI). If your quota is exhausted, the metered endpoints return 400.

---

Importing into Postman / Insomnia

The full request collection is generated from the OpenAPI spec — there is no file to download or maintain.

1. In Postman, choose File → Import → Link (Insomnia: Import → From URL).
2. Paste: https://hr.cocolevio.com/partner-api/openapi.json

Every endpoint, its parameters, and sample payloads are imported automatically.

Live interactive docs

Browse and try endpoints in ReDoc at https://hr.cocolevio.com/developers. The "Try it" host defaults to the environment you are viewing the docs from.

---

Common response codes

Related reading

• How AI scoring works
• Anti-cheat and proctoring
• Security and privacy
• Responsible AI and fairness
• FAQ · Troubleshooting