Endpoint: Creating a Candidate

This endpoint lets you create a candidate under one of your tasks.

There are 2 kinds of candidates you can create under a task: temporary and internal. Internal candidates are created from the users under your organization. 

There are some common properties between the two kinds of candidates:

// Common properties - all optional
{
  group?: string;
  labels?: string[];
  tags?: Record;

  externalId?: string;
  externalData?: Record;

  lang?: "tr" | "en" | "es" | "fr" | "nl" | "it" | "sr" | "sv" | "de" | "no" | "ru" | "pt";
  programIds?: string[];
  extraEmails?: string[];
  dates?: {
    before?: number;// seconds
    after?: number;// seconds
  };
  price?: {
    amount: number;
    currency: "USD" | "EUR" | "TRY";
  };
  customizedSteps?: {
    stepId: string;
    customization: {
      activeAfter?: number; //seconds;
      activeBefore?: number; //seconds
    };
  }[];

  inviteByEmail?: {
    emailTemplateName: string
    dateToSend?: number; // seconds
  };
  callback?: {
    url: string;
    params?: Record;
    resource: "basic" | "detailed";
  };
}

• group: The candidate's group. It's used for sorting & filtering candidates. If not provided, a default value is assigned. This value will copied over to each of the candidate's test sessions.
• labels: Candidate's labels. It's used for sorting & filtering candidates. This value will copied over to each of the candidate's test sessions.
• tags: Candidate's tags. It's used for sorting & filtering candidate. This value will copied over to each of the candidate's test sessions.
• externalId: The candidates uuid on your end.
• externalData: Any extra information from your end you wish to attach to the candidate.
• lang: The interface language that will be set for the candidate upon them accessing their assessment. If not provided, the task's default language is used.
• programIds: The ids of the task programs to which the candidate will assigned. With programs, which task steps are accessible can be controlled.
• externalEmails: Extra email addresses that will be stored with the candidate. When sending an email, these emails can be cc'd as well.
• dates: Dates after or before which the candidate can log in and access their assignment.
• price: A price of admission that the candidate is required to pay in order to access the assessment.
• customizedSteps: Customizations of task steps only for this candidate. By providing a step's id, certain customizations can be set.
• inviteByEmail: If there are email templates saved inside the task, an invitation email can be sent to the candidate's email address (if provided) immediately after the candidate's creation by providing the template's name with emailTemplateName . Alternatively, the email can be scheduled for future by providing a date with dateToSend.
• callback: If provided, an automatic callback can be set that will send the candidate's test session information to the given url after the candidate completes a test session. The information that will be sent will be the same as the information provided by Test Session Seach Endpoint.

The expected body for Temporary Candidate:

Common & {
  kind: "temporary-candidate";
  fullname?: string;
  email?: string;
  credential1?: string;
  credential2?: string;

  tracking?: {
    uniqId: string;
    scope?: "task" | "group" | "labels" | "programs";// default: task
  };
}

By providing the tracking property with a uniqId, the uniqueness of this candidate within the provided scope can be ensured. Within the given scope, Testinvite does not allow the creation of a candidate with a duplicate uniqId. 

The expected body for Internal Candidate:

Common & {
  kind: "internal-candidate";
  id: string; // userId
}

The full name and email information will copied over from the user. The tags of the candidate will be the sum of the tags from the user and the ones provided in the request body.

The username of the user will be assigned as the uniqId of the candidate in order to ensure that user is assigned to the task only once. The username will be assigned also as the first credential of the candidate. The candidate will be able to access the their assessment using their username as their credential. 

Response

If the request is successful, the response payload will be as follows: 

// "basic" candidate object
{
    candidateId: string;
    kind: "user" | "temp"; // internal or temporary candidate
    taskId: string;
    loggedIn: false;

    fullname?: string;
    email?: string;
    invitationCode: string;
}