Endpoint: Updating a Candidate

This endpoint lets you update some properties of a candidate under a task.

Request Body

 {
      fields: {
        fullname?: string;
        email?: string;

        group?: string;
        labels?: {
          add?: string[];
          remove?: string[];
        };
        favorite?: boolean;

        active?: boolean;
        activeAfter?: number; //seconds;
        activeBefore?: number; //seconds;
     };
     steps?: Record<
       string, // step id
       {
         active?: { isDefault: true } | { isDefault: false; value: boolean };
         dates?: { isDefault: true } | {
           isDefault: false;
           value: {
             after?: number /* seconds */ | null;
             before?: number /* seconds */ | null;
           };
         limit?: { isDefault: true } | { isDefault: false; value: number /* -1 for unlimited attempts */};
       }
    >;
};

Customizations for a candidate in a specific step can be made by pairing up the respective step id with the update data under "steps" property.

Under "steps", the updated value of a property can be reverted back to its default value with { isDefault: true }. The default values come from the task's own step settings.

For "dates" under "steps", a "before" or "after" date can be set by assigning a timestamp value in seconds. Setting either date's value to null will remove the date restriction. If either date's value if omitted, the existing value of the  date will not be changed.

Response

Upon a successful request, a "detailed" candidate object will be returned.

// "detailed" candidate object
{
    candidateId: string;
    kind: "user" | "temp"; // internal or temporary candidate
    taskId: string;
    loggedIn: boolean;
    fullname?: string;
    email?: string;
    invitationCode: string | null;// null for kind: "user"
  
    organizationId: string;
    source: "self-registration" | "pre-registration";
    active: boolean;
    activeAfter: number | null; // seconds
    activeBefore: number  | null; // seconds

    group: string;
    tags: Record<
      string, 
      string
    >;
    labels: string[];

    rating: 1 | 2 | 3 | 4 | 5 | null;
    stage: string | null;
}