API Documentation

Integrate truelevel into your hiring workflow with our REST API. Submit candidate artefacts programmatically and receive structured evaluation results.

Authentication

All API requests require an organisation-level API key. Include your key in the Authorization header with each request.

Authorization: Bearer tl_live_your_api_key

API keys are scoped to your organisation and can be generated from the dashboard. Keep your keys secure and never expose them in client-side code.

Endpoints

The truelevel API provides three core endpoints for managing evaluations.

POST/evaluations

Submit a new candidate artefact for evaluation. Returns immediately with an evaluation ID.

GET/evaluations/{id}

Retrieve a completed evaluation with full results, rubric scores, and risk flags.

GET/status/{id}

Check the current status of an in-progress evaluation.

POST

/evaluations

Submit a candidate artefact for evaluation. The request returns immediately with an evaluation ID that you can use to check status or retrieve results.

Request body

Requestjson

{
  "candidate_ref": "CAND-2024-0847",
  "target_role": "Backend Engineer",
  "target_level": "senior",
  "artefact": {
    "type": "github_repo",
    "url": "https://github.com/candidate/take-home-project"
  },
  "sla_tier": "priority",
  "callback_url": "https://your-ats.com/webhooks/truelevel"
}

candidate_refYour internal candidate identifier. Used in reports for reference.

target_roleThe role title the candidate is applying for.

target_levelExpected seniority: junior, mid, senior, or staff.

artefactThe code submission. Supports github_repo or zip_upload.

sla_tierTurnaround preference: standard (24h), priority (12h), or express (2h).

callback_urlOptional. URL to receive a webhook when evaluation completes.

Response

Response (201 Created)json

{
  "id": "eval-2024-0847",
  "status": "pending",
  "candidate_ref": "CAND-2024-0847",
  "target_role": "Backend Engineer",
  "target_level": "senior",
  "sla_tier": "priority",
  "estimated_completion": "2024-01-15T21:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}

GET

/evaluations/{id}

Retrieve a completed evaluation. Returns the full structured report including recommendation, rubric scores, calibrated seniority, and any risk flags.

Response

Response (200 OK)json

{
  "id": "eval-2024-0847",
  "status": "completed",
  "candidate_ref": "CAND-2024-0847",
  "target_role": "Backend Engineer",
  "target_level": "senior",
  "completed_at": "2024-01-15T14:45:00Z",
  "turnaround_hours": 5.25,
  "result": {
    "recommendation": "proceed",
    "confidence_score": 92,
    "calibrated_seniority": "senior",
    "rubric_scores": [
      {
        "category": "Code Quality",
        "score": 4,
        "max_score": 5,
        "observations": [
          "Consistent naming conventions throughout",
          "Appropriate use of abstractions",
          "Error handling present but could be more comprehensive"
        ]
      },
      {
        "category": "Technical Depth",
        "score": 4,
        "max_score": 5,
        "observations": [
          "Good understanding of database optimisation",
          "Correctly identifies concurrency concerns"
        ]
      },
      {
        "category": "Reasoning and Trade-offs",
        "score": 5,
        "max_score": 5,
        "observations": [
          "Clearly articulates design pattern choices",
          "Considers operational concerns"
        ]
      }
    ],
    "risk_flags": []
  }
}

See the sample report page for a visual representation of this data.

GET

/status/{id}

Check the current status of an evaluation. Useful for polling while waiting for results, though we recommend using webhooks when available.

Response

Response (200 OK)json

{
  "id": "eval-2024-0847",
  "status": "in_progress",
  "candidate_ref": "CAND-2024-0847",
  "progress": {
    "stage": "review",
    "started_at": "2024-01-15T10:15:00Z"
  },
  "estimated_completion": "2024-01-15T14:30:00Z"
}

Status values:

pending — Submitted, waiting for reviewer assignment
in_progress — Reviewer has started the evaluation
completed — Evaluation finished, results available
failed — Unable to evaluate (e.g., inaccessible artefact)

Coming later

The following features are planned for future releases.

Webhooks

Planned

Receive real-time notifications when evaluations complete, eliminating the need for polling.

ATS integrations

Planned

Native integrations with Greenhouse, Lever, Ashby, and other popular applicant tracking systems.

Ready to integrate?

Request pilot access to receive your API credentials and start submitting evaluations.

Request pilot access Contact us