Example: send an interview from an ATS

The whole flow an applicant tracking system needs, as real requests: list roles, invite a candidate, poll the interview, and read the decision.

The flow#

A recruiter picks an EasyEnv role for a job. When a candidate reaches that stage, your system invites them. EasyEnv emails the candidate, they take the interview on a real machine, and your team reviews it in EasyEnv. Your system follows along and shows the outcome on the candidate.

The examples use these variables:

bash
API=https://api.easyenv.io/v1
EASYENV_TOKEN=...      # see Authentication
EASYENV_ACCOUNT=...    # the account's uuid, from GET /v1/accounts/

1. List roles#

A role is what a candidate is interviewed on. Offer these to the recruiter:

bash
curl "$API/interviews/?page_size=200&sort=a-z" \
  -H "X-Service-Token: $EASYENV_TOKEN" \
  -H "Account-ID: $EASYENV_ACCOUNT"
json
{
  "count": 2,
  "total_pages": 1,
  "links": { "next": null, "previous": null },
  "results": [
    { "uuid": "r7p2k9xa", "title": "Backend Engineer", "duration": 60, "duration_unit": "minutes", ... },
    { "uuid": "m4t8w1qe", "title": "SRE", "duration": 90, "duration_unit": "minutes", ... }
  ]
}

Archived roles are left out. Keep the uuid of the one the recruiter picks.

2. Invite the candidate#

Create a take-home assignment on the role. The body is form fields, not JSON:

bash
curl -X POST "$API/interviews/r7p2k9xa/interview-items/" \
  -H "X-Service-Token: $EASYENV_TOKEN" \
  -H "Account-ID: $EASYENV_ACCOUNT" \
  -F type=offline \
  -F [email protected] \
  -F interviewee_name="Jane Doe" \
  -F start_date=2026-09-18 \
  -F end_date=2026-09-25 \
  -F timezone=Europe/London
FieldTypeDescription
interviewee_emailrequiredstringWhere the invitation goes. It cannot be a member of the account.
typerequiredstringoffline: the candidate takes it on their own, inside the window. Leave it out and you get a live interview instead.
start_date / end_dateYYYY-MM-DDThe window the candidate can start in. Set both: a take-home assignment without an end date never expires.
timezoneIANA nameThe time zone the window is read in. Defaults to UTC.
interviewee_namestringShown to reviewers and used in the email.
titlestringA name for this interview in the dashboard.
candidate_resumePDF fileUp to 5 MB, for reviewers.

A 201 means the invitation email is on its way:

json
{
  "uuid": "q9z3v6nd",
  "type": "offline",
  "candidate_email": "[email protected]",
  "interviewee_name": "Jane Doe",
  "start_date": "2026-09-18",
  "end_date": "2026-09-25",
  "timezone": "Europe/London",
  ...
}

Store uuid against the candidate: it is the interview you will poll. Each call creates a new interview and emails the candidate, so if a request times out, check the role's interviews before you retry, or they get two invitations. The plan spends an interview only when the candidate starts.

3. Follow the interview#

bash
curl "$API/interviews/r7p2k9xa/interview-items/q9z3v6nd/" \
  -H "X-Service-Token: $EASYENV_TOKEN" \
  -H "Account-ID: $EASYENV_ACCOUNT"

The answer has two shapes. Until the candidate starts, it describes the invitation. Once they start, it describes their sitting, and it gains an attempt_uuid field; that is how you tell them apart.

json
// Not started yet
{ "uuid": "q9z3v6nd", "status": "invited", "end_date": "2026-09-25", ... }

// Started
{
  "uuid": "q9z3v6nd",
  "attempt_uuid": "h2c8j5rt",
  "status": "needs_review",
  "review_status": null,
  "started_at": "2026-09-19T09:02:11Z",
  "ended_at": "2026-09-19T10:01:40Z",
  "time_spent": 3569.0,
  ...
}

Statuses#

Before the candidate starts (no attempt_uuid):

FieldTypeDescription
invitedEmailed, not started.
readyThe candidate has an EasyEnv sign-in and can start. Treat it like invited.
startedThe candidate has started. This endpoint switches to the started shape at that moment, so you rarely see this value here.
expiredThe window closed and the candidate never started. Expiry is applied once a day at 00:00 UTC, so it can show up to a day late.

After the candidate starts (attempt_uuid present):

FieldTypeDescription
in_progressThe candidate is taking the interview.
needs_reviewSubmitted. Waiting for someone on the team to review it.
review_completedReviewed. review_status holds the decision.
not_completedThe sitting ended without a submission, for example it ran out of time.

Most ATSs map these to four stages: invited (invited, ready), started (started, in_progress), submitted (needs_review) and completed (review_completed), with expired and not_completed as cancelled.

4. Read the decision#

When status is review_completed, review_status is accepted or rejected, which the app shows as Passed and Failed. That is a person's decision on the review page, not an automatic score, and it is the result to show on the candidate. Until someone decides, it is null.

No score in the API yet
The review page shows auto-graded answers and an AI review, but the API does not return a summary score for an interview today. Link to the review page for the detail. The started shape has a result field, but it is reserved and is null today; do not build on it.

Give recruiters a link from the candidate in your system to the full review in EasyEnv. It opens for anyone signed in to EasyEnv with access to the account:

https://dashboard.easyenv.io/dashboard/{account uuid}/feedback/{role uuid}/{interview uuid}

Built something with this, or need a call that is not here? Write to [email protected].

Example: send an interview from an ATS | Docs | EasyEnv