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?: { isDefault: true } | { isDefault: false; value: number /* seconds */ | null };
             before?: { isDefault: true } | { isDefault: false; value: 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 the date's value to null will remove the date limitation entirely. If omitted, the respective date's value 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;
}