v1.0.0
OpenAPI 3.1.0

HackerEarth OnScreen API

HackerEarth Support
Terms of Service

REST API for scheduling and managing AI-powered interviews.

Authentication

Send your API key in the X-Helix-API-Key header of every request. HackerEarth issues API keys; contact your account manager to request one. A missing, unknown or revoked key, or a deactivated company, returns 401 with the code MISSING_API_KEY, INVALID_API_KEY, API_KEY_REVOKED or COMPANY_INACTIVE.

Errors

Every error response, including authentication failures (401) and requests the API rejects before reaching an endpoint (403, 406) or while reading the request body (415), returns {"success": false, "error": {...}}. The error object carries a code and a message, plus a suggestion and details when available. Branch on code; the message is for people. An HTTP method an endpoint does not support returns 405 with the code METHOD_NOT_ALLOWED.

Pagination

Listing interviews is paginated. Pass page and page_size (default 10, maximum 100). The response carries count, next, previous, results and total_count.

Interview lifecycle

status is derived in this order, first match wins: cancelled (the interview was cancelled), completed (the candidate finished it), ongoing (started, not finished), expired (the deadline passed before it started), otherwise upcoming.

candidate_status is null until the interview ends. It can be set only after the interview ends; before that the API returns INTERVIEW_NOT_COMPLETED.

report_status appears on the interview detail. It is null until the interview ends, then IN_PROGRESS, READY, FAILED or NOT_EVALUATED.

Datetimes

Every datetime in a response is UTC, ISO 8601 with an explicit +00:00 offset. deadline_formatted is a UTC display string. For the deadline_time you send, an offset inside the value wins; otherwise timezone applies, then the timezone of the API key's creator, then UTC.

Duplicates and retries

There is no Idempotency-Key header. Scheduling the same candidate email and template while an interview is still open returns 400 with the code DUPLICATE_INTERVIEW and the existing interview_id. After a timeout, retry the schedule request and handle that response, or list interviews with candidate_email first.

Rate limits

Scheduling an interview is limited to 50 requests per second per API key. Beyond that the API returns 429 with the code RATE_LIMITED; retry later. No Retry-After header is sent, so back off exponentially. No other endpoint has an application-level rate limit.

Listing interviews

Results are newest first. candidate_email is an exact, case-insensitive match. There are no date filters. page_size is at most 100.

API keys

A key belongs to one company; a company can have several keys. Keys do not expire. HackerEarth issues and revokes keys on request through your account manager. Send a key only in the header, over HTTPS.

Environments

There is one environment, production, and no sandbox. To test, schedule an interview for your own email on a test template. Every interview you schedule consumes credits; without enough credits the API returns INSUFFICIENT_CREDITS.

Versioning

The version is in the URL path (/v1). New fields, error codes and enum values may be added without notice; ignore ones you do not know. Breaking changes ship only in a new /vN, and /v1 is retired no sooner than 6 months after notice.

Webhooks

Interview events are delivered to your company webhook, documented at https://www.hackerearth.com/docs/webhooks/recruiter/v1/. Your account manager configures it. The interview object in a payload has the same shape as ExternalInterview and ExternalInterviewDetail in this API.

Personal data and retention

Responses and webhooks contain the candidate's name and email. Interview data is kept until it is deleted. Send deletion requests to support@hackerearth.com.

Server:https://api.hackerearth.com/ai-interviewer/api/v1

Production

Client Libraries
Shell Curl

Interviews

​

Schedule interviews, follow their status, read reports and manage candidates.

Interviews Operations

List interviews

​

List the interviews of one template, newest first. Filter by status or candidate_email; results are paginated.

Query Parameters

  • candidate_email
    Type: string

    Filter by candidate email.

  • include
    enum
    const:  
    report

    Only for OnScreen templates: report adds each interview's lean report as report (null when the interview has not ended or its report is still being evaluated; PendingReport when evaluation failed or was skipped).

  • page
    Type: integer

    A page number within the paginated result set.

  • page_size
    Type: integer
    max:  
    100

    Number of results per page; larger values are capped.

  • status
    Type: stringenum

    Filter by interview status. An unknown value returns 400 VALIDATION_ERROR.

    values
    cancelledcompletedexpiredongoingupcoming
  • template_uuid
    Type: string
    required

    Template UUID, as returned by the template list.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/interviews/
curl 'https://api.hackerearth.com/ai-interviewer/api/v1/interviews/?page_size=10&template_uuid=' \
  --header 'X-Helix-API-Key: YOUR_SECRET_TOKEN'

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f",
      "title": "Senior Backend Engineer",
      "candidate_name": "Alex",
      "candidate_email": "alex@example.com",
      "status": "upcoming",
      "interview_url": "https://www.hackerearth.com/api/v1/onscreen/interviews/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/login/?login=a1b2c3d4e5f6",
      "deadline": "2026-11-30T23:59:59+00:00",
      "deadline_formatted": "Nov 30, 2026 11:59 PM UTC",
      "start_time": null,
      "end_time": null,
      "template_title": "Senior Backend Engineer",
      "candidate_status": null,
      "template_uuid": "0123456789abcdef0123456789abcdef"
    }
  ],
  "total_count": 1
}

Retrieve interview details

​

Returns interview fields plus invite_sent, report_status, and full report projection (FullReport) when available.

Path Parameters

  • uuid
    Type: string
    required

    Interview id as returned by schedule and list.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/interviews/{uuid}/
curl 'https://api.hackerearth.com/ai-interviewer/api/v1/interviews/{uuid}/' \
  --header 'X-Helix-API-Key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "interview": {
    "id": "5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f",
    "title": "Senior Backend Engineer",
    "candidate_name": "Alex",
    "candidate_email": "alex@example.com",
    "status": "upcoming",
    "interview_url": "https://www.hackerearth.com/api/v1/onscreen/interviews/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/login/?login=a1b2c3d4e5f6",
    "deadline": "2026-11-30T23:59:59+00:00",
    "deadline_formatted": "Nov 30, 2026 11:59 PM UTC",
    "start_time": null,
    "end_time": null,
    "template_title": "Senior Backend Engineer",
    "candidate_status": null,
    "template_uuid": "0123456789abcdef0123456789abcdef",
    "invite_sent": true,
    "report_status": null,
    "failure_reason": null,
    "report": null
  }
}

Cancel an interview

​

Cancel an interview that has not started, ended, expired or been cancelled.

Path Parameters

  • uuid
    Type: string
    required

    Interview id as returned by schedule and list.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/interviews/{uuid}/cancel/
curl 'https://api.hackerearth.com/ai-interviewer/api/v1/interviews/{uuid}/cancel/' \
  --request POST \
  --header 'X-Helix-API-Key: YOUR_SECRET_TOKEN'
Interview cancelled
{
  "success": true,
  "message": "Interview cancelled successfully.",
  "interview": {
    "id": "5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f",
    "title": "Senior Backend Engineer",
    "candidate_name": "Alex",
    "candidate_email": "alex@example.com",
    "status": "cancelled",
    "interview_url": "https://www.hackerearth.com/api/v1/onscreen/interviews/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/login/?login=a1b2c3d4e5f6",
    "deadline": "2026-11-30T23:59:59+00:00",
    "deadline_formatted": "Nov 30, 2026 11:59 PM UTC",
    "start_time": null,
    "end_time": null,
    "template_title": "Senior Backend Engineer",
    "candidate_status": null,
    "template_uuid": "0123456789abcdef0123456789abcdef"
  }
}

Get the interview report

​

null means the interview has not ended or its report is still being evaluated. Once the report is ready, format=lean (default) returns LeanReport and format=full returns FullReport. If evaluation failed or was skipped, either format returns PendingReport.

Path Parameters

  • uuid
    Type: string
    required

    Interview id as returned by schedule and list.

Query Parameters

  • format
    Type: "full" or "lean"enum

    Report detail level.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/interviews/{uuid}/report/
curl 'https://api.hackerearth.com/ai-interviewer/api/v1/interviews/{uuid}/report/?format=lean' \
  --header 'X-Helix-API-Key: YOUR_SECRET_TOKEN'
Lean report
{
  "report_version": "v4",
  "resume_status": "used",
  "overall": {
    "score": 78,
    "summary": "Solid backend fundamentals with clear communication."
  },
  "readiness": {
    "score": 78
  },
  "skills": [
    {
      "key": "101",
      "title": "Python",
      "score": 82
    },
    {
      "key": "102",
      "title": "System Design",
      "score": 74
    }
  ],
  "key_assessment_points": [
    {
      "kind": "strength",
      "skill_key": "101",
      "text": "Explained trade-offs between sync and async I/O clearly."
    },
    {
      "kind": "further_investigation",
      "skill_key": null,
      "text": "Limited detail on production incident handling."
    }
  ],
  "integrity": {
    "status": "good"
  }
}

Resend the interview invitation

​

Resend the invitation email of an interview that has not started, ended, expired or been cancelled and is no longer being prepared.

Path Parameters

  • uuid
    Type: string
    required

    Interview id as returned by schedule and list.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/interviews/{uuid}/resend-invite/
curl 'https://api.hackerearth.com/ai-interviewer/api/v1/interviews/{uuid}/resend-invite/' \
  --request POST \
  --header 'X-Helix-API-Key: YOUR_SECRET_TOKEN'
Invitation resent
{
  "success": true,
  "message": "Invitation email resent successfully."
}

Update the candidate status

​

Set the candidate status of a completed interview to under_review, shortlisted or archived.

Path Parameters

  • uuid
    Type: string
    required

    Interview id as returned by schedule and list.

Body·

required

Request body for updating the candidate status of a completed interview.

  • candidate_status
    Type: enum
    required
    values
    under_reviewshortlistedarchived

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/interviews/{uuid}/update-candidate-status/
curl 'https://api.hackerearth.com/ai-interviewer/api/v1/interviews/{uuid}/update-candidate-status/' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Helix-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "candidate_status": "shortlisted"
}'
Candidate status updated
{
  "success": true,
  "message": "Candidate status updated to shortlisted.",
  "interview": {
    "id": "5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f",
    "title": "Senior Backend Engineer",
    "candidate_name": "Alex",
    "candidate_email": "alex@example.com",
    "status": "completed",
    "interview_url": "https://www.hackerearth.com/api/v1/onscreen/interviews/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/login/?login=a1b2c3d4e5f6",
    "deadline": "2026-11-30T23:59:59+00:00",
    "deadline_formatted": "Nov 30, 2026 11:59 PM UTC",
    "start_time": "2026-11-20T10:00:00+00:00",
    "end_time": "2026-11-20T10:25:00+00:00",
    "template_title": "Senior Backend Engineer",
    "candidate_status": "shortlisted",
    "template_uuid": "0123456789abcdef0123456789abcdef",
    "invite_sent": true,
    "report_status": "IN_PROGRESS",
    "failure_reason": null,
    "report": null
  }
}

Schedule an interview

​

Schedule an interview. Optional resume (file/text/url). deadline_time is required. A second request for the same candidate email and template while an interview is still open (not expired, ended or cancelled) returns 400 DUPLICATE_INTERVIEW; the error carries the existing interview_id.

Body·

required

Request body for scheduling an interview.

Identify the template with template_uuid. Without a resume, candidate_name and candidate_email are required; with a resume they override the values extracted from it. Give at most one resume source: resume_file_b64 with resume_file_name, resume_text or resume_url. deadline_time is required.

  • deadline_time
    Type: stringFormat: date-time
    required

    ISO 8601 datetime. An offset in the value (Z or +05:30) wins; otherwise timezone applies, then the API key creator's profile timezone, then UTC. Must be in the future.

  • template_uuid
    Type: string
    required

    UUID of the template to schedule, as returned by the template list.

  • candidate_email
    Type: stringFormat: email
  • candidate_name
    Type: string
    max length:  
    200
  • resume_file_b64
    Type: string
  • resume_file_name
    Type: string
  • resume_text
    Type: string
  • resume_url
    Type: string
  • send_email_invite
    Type: boolean
  • timezone
    Type: string

    IANA timezone name, e.g. Asia/Kolkata. Used only when deadline_time has no offset; an unknown name returns 400.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/interviews/schedule/
curl https://api.hackerearth.com/ai-interviewer/api/v1/interviews/schedule/ \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Helix-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "candidate_name": "Alex Thompson",
  "candidate_email": "alex@example.com",
  "template_uuid": "0123456789abcdef0123456789abcdef",
  "deadline_time": "2026-11-30T23:59:59Z",
  "send_email_invite": true
}'
Interview scheduled
{
  "success": true,
  "interview_id": "5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f",
  "interview": {
    "id": "5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f",
    "title": "Senior Backend Engineer",
    "candidate_name": "Alex",
    "candidate_email": "alex@example.com",
    "status": "upcoming",
    "interview_url": "https://www.hackerearth.com/api/v1/onscreen/interviews/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/login/?login=a1b2c3d4e5f6",
    "deadline": "2026-11-30T23:59:59+00:00",
    "deadline_formatted": "Nov 30, 2026 11:59 PM UTC",
    "start_time": null,
    "end_time": null,
    "template_title": "Senior Backend Engineer",
    "candidate_status": null,
    "template_uuid": "0123456789abcdef0123456789abcdef"
  },
  "message": "Interview scheduled. Alex will receive an invitation email."
}

Templates (Collapsed)

​

List the interview templates available to your company.

Templates Operations

Models