Project’s Candidates¶

Please read about the Candidate workflow before diving into this page.

Attributes

Name	Type	Description
resource_uri	reference	read only
first_name	string
last_name	string
username	string	optional
status	string	read only See: Advance Status Action Candidate workflow Skip Status Action
confirmationdate	timestamp	optional
photo	reference	optional
cv	reference	optional Tries to recognise MIME type of uploaded file. Supported types are: `application/msword`, `application/pdf`, `application/postscript`, `application/vnd.ms-powerpoint`, `application/x-dvi`, `text/plain`, `text/richtext` Returns reference to candidate’s CV. See more.
evaluation_status	string	optional, read only possible values are: `pending`, `partial`, `completed` See more.
my_evaluation_status	string	optional, read only possible values are: `null`, `pending`, `completed` See more.
email	string
project	reference	optional
phone	string	optional
gender	string	optional
created_by	string	optional
address	string	optional
deadline	timestamp	optional
invitationdate	timestamp	optional
interviewdate	timestamp	optional
partner_data	object	this field is for internal use and provides no additional functionality
shares	list	read only available for Interview Manager and Account Owner/Admin List of customers candidate is shared with
interview_suite_url	string	read only The URL that leads directly to the appropriate interview suite page for this record

List¶

/companies/{{companyId}}/projects/{{projectId}}/candidates/

Methods

GET
POST

Example response

{"meta":{
    "total_count":1,
    "previous":null,
    "next":null
 },
 "objects":[
    {"resource_uri": "https://interview-suite.com/api/v3/companies/4/projects/14/candidates/521/",
     "photo": "https://interview-suite.com/api/v3/companies/4/projects/14/candidates/521/photo/a76b5e78cd3/",
     "first_name": "Francisco",
     "last_name": "Assis",
     "gender": "mr",
     "email": "francisco.assis@viasto.com",
     "status": "interviewed",
     "company": "https://interview-suite.com/api/v3/companies/4/",
     "interview_key": "abc68df6c4b354b61f8b2e1094503210",
     "project": "https://interview-suite.com/api/v3/companies/4/projects/14/",
     "evaluation_status": "pending",
     "invitationdate": "2015-06-19T12:19:36Z",
     "confirmationdate": "2015-06-19T12:24:11Z",
     "interviewdate": "2015-06-19T12:29:42Z",
     "deadline": "2015-06-30T08:00:00Z",
     "activation_key": "06d592a9c52aa220af5bdf7aab308e32",
     "created_by": "https://interview-suite.com/api/v3/customusers/1/",
     "username": "assis9405",
     "partner_data": {},
     "shares": [
      {
          "resource_uri": "https://interview-suite.com/api/v3/companies/4/projects/14/candidates/521/shares/1/",
          "customer": "https://interview-suite.com/api/v3/companies/4/customers/5/",
          "candidate": "https://interview-suite.com/api/v3/companies/4/projects/14/candidates/521/"
      },
      {
          "resource_uri": "https://interview-suite.com/api/v3/companies/4/projects/14/candidates/521/shares/2/",
          "customer": "https://interview-suite.com/api/v3/companies/4/customers/7/",
          "candidate": "https://interview-suite.com/api/v3/companies/4/projects/14/candidates/521/"
      }],
    }
   ]
 }

Object¶

/companies/{{companyId}}/projects/{{projectId}}/candidates/{{candidateId}}/

Methods

GET
PATCH
DELETE

Example response

{"resource_uri": "https://interview-suite.com/api/v3/companies/4/projects/14/candidates/521/",
 "photo": "https://interview-suite.com/api/v3/companies/4/projects/14/candidates/521/photo/a76b5e78cd3/",
 "first_name": "Francisco",
 "last_name": "Assis",
 "gender": "mr",
 "email": "francisco.assis@viasto.com",
 "status": "interviewed",
 "company": "https://interview-suite.com/api/v3/companies/4/",
 "interview_key": "abc68df6c4b354b61f8b2e1094503210",
 "project": "https://interview-suite.com/api/v3/companies/4/projects/14/",
 "evaluation_status": "pending",
 "invitationdate": "2015-06-19T12:19:36Z",
 "confirmationdate": "2015-06-19T12:24:11Z",
 "interviewdate": "2015-06-19T12:29:42Z",
 "deadline": "2015-06-30T08:00:00Z",
 "activation_key": "06d592a9c52aa220af5bdf7aab308e32",
 "created_by": "https://interview-suite.com/api/v3/customusers/1/",
 "username": "assis9405"
}

Set Deadline Action¶

Used to change a candidate’s deadline. Only a deadline attribute is required in the JSON payload. The deadline must follow the ISO 8601 standard and must include a time zone designator, so for example: 2022-11-11T23:59+01:00 (for one minute before midnight in CET) or 2022-11-11T23:59Z (for one minute before midnight in UTC).

/companies/{{companyId}}/projects/{{projectId}}/candidates/{{candidateId}}/deadline/

Methods

PATCH

Advance Status Action¶

Used to change a candidate’s status to the next state (see Workflow -> Candidate). Certain role-based restrictions apply.

Project Managers can call this action to transition a project candidate from:

new to invited
aborted to confirmed
expired to invited (if the candidate has not set a password)
expired to confirmed (if the candidate has set a password)

The Candidate themself can call this action to transition from:

invited to confirmed
confirmed to interviewing
interviewing to interviewed (not implemented)

The status will only change through a valid transition that matches to conditions as defined in the state machine. In case a required condition is not matching, a “400 Bad Request” response is returned with respective error message.

To be able to advance from new to invited the deadline of the candidate needs to be in the future and the candidate should have a non-empty email.

In order to advance from aborted to confirmed or from expired to invited/confirmed, the deadline of the candidate needs to be in the future otherwise the request would be rejected with “400 Bad Request”.

Update the deadline before trying to advance from aborted or expired.

No payload is required.

/companies/{{companyId}}/projects/{{projectId}}/candidates/{{candidateId}}/status/advance/

Methods

PATCH

“Skip” Status Action¶

This functionality is in active development. Please contact viasto support before using this in production.

Used to set a candidate’s status to “skipped” (“won’t interview”) to indicate that there will be no further action from this candidate. “Skipped” candidates will not receive notification mails and are unable to log in to the candidate frontend.

Only candidates that have not completed (or started) an interview can be set to “skipped”, i.e. candidates with status:

new

invited

confirmed

expired

aborted

No payload is required. Once a candidate is “skipped” they cannot be un-skipped. There is no way to set them as able to do their interview again.

/companies/{{companyId}}/projects/{{projectId}}/candidates/{{candidateId}}/status/skip/

Methods

PATCH

Trigger Reminder Email Action¶

Used by Project Managers to send reminder emails to candidates with status invited or confirmed

No payload is required.

/companies/{{companyId}}/projects/{{projectId}}/candidates/{{candidateId}}/reminder/

Methods

POST

Photo and CV¶

You can upload a photo or a CV for a candidate when creating them (POST) or when updating them (PATCH). Photo and CV uploads must be multipart/form-data encoded. Additionally the photo can be uploaded as data URI.

multipart/form-data examples:

curl -X POST -H 'Authorization: Token <your token>' \
-F "photo=@profile-picture.jpg" \
-F "first_name=Luke" \
-F "last_name=Skywalker" \
-F "email=luke.skywalker@darkside.moon" \
-F "gender=mr" \
https://interview-suite.com/api/v3/companies/2/projects/9/candidates/

curl -X PATCH -H 'Authorization: Token <your token>' \
-F "photo=@profile-picture.jpg" \
https://interview-suite.com/api/v3/companies/2/projects/9/candidates/51/

Data URI examples:

curl -X POST \
-H 'Authorization: Token <your token>' \
-H 'Content-Type: application/json' \
-d '{ \
  "first_name": "Luke", \
  "last_name": "Skywalker", \
  "email": "max.ludwig@viasto.com", \
  "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABGdBTUEAALGPC/xhBQAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9YGARc5KB0XV+IAAAAddEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIFRoZSBHSU1Q72QlbgAAAF1JREFUGNO9zL0NglAAxPEfdLTs4BZM4DIO4C7OwQg2JoQ9LE1exdlYvBBeZ7jqch9//q1uH4TLzw4d6+ErXMMcXuHWxId3KOETnnXXV6MJpcq2MLaI97CER3N0vr4MkhoXe0rZigAAAABJRU5ErkJggg==" \
}' \
https://interview-suite.com/api/v3/companies/2/projects/9/candidates/

curl -X PATCH \
-H 'Authorization: Token <your token>' \
-H 'Content-Type: application/json' \
-d '{"photo":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABGdBTUEAALGPC/xhBQAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9YGARc5KB0XV+IAAAAddEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIFRoZSBHSU1Q72QlbgAAAF1JREFUGNO9zL0NglAAxPEfdLTs4BZM4DIO4C7OwQg2JoQ9LE1exdlYvBBeZ7jqch9//q1uH4TLzw4d6+ErXMMcXuHWxId3KOETnnXXV6MJpcq2MLaI97CER3N0vr4MkhoXe0rZigAAAABJRU5ErkJggg=="}'
https://interview-suite.com/api/v3/companies/2/projects/9/candidates/51/

Note

The URL of a photo or a CV is generated with time limited token for security concerns and provided by candidate resource response, which means each user session will get different tokens every time candidate is requested. The token expires when the authorization token expires.

Depending on content a valid content type is returned (i.e. JPEG, PNG, PDF).

Import (Bulk Insert)¶

This method was introduced to simplify import of many candidates to a project. It receives a list of candidates to create, and then applies Set Deadline Action and Advance Status Action to each of them.

/companies/{{companyId}}/projects/{{projectId}}/candidates/import/

Methods

POST

Project’s Candidates¶

List¶

Object¶

Set Deadline Action¶

Advance Status Action¶

“Skip” Status Action¶

Trigger Reminder Email Action¶

Photo and CV¶

Import (Bulk Insert)¶

Navigation

Table of Contents