--- title: "application.updateHistory" method: POST path: "/application.updateHistory" tags: ["Application"] --- # application.updateHistory `POST /application.updateHistory` Update the history of an application. Used to update stage timestamps and to delete history events. **Also requires the `Allow updating application history?` setting found in your admin API key permissions configuration.** **Requires the [`candidatesWrite`](authentication#permissions-applicationupdatehistory) permission.** ## Request body - ApplicationUpdateHistoryRequest - `applicationId` string, uuid, required — The id of the application whose history to update. - `applicationHistory` object[], required — The updated array of application history events. This array should contain all history events for the application, not just the events being updated. - `stageId` string, uuid, required — The id of the interview stage for this history event. Must belong to the application's interview plan. - `stageNumber` integer, required — The sort order of this event. 0 is the first, the highest number will be the current stage. - `enteredStageAt` string, date-time, required — An ISO date string representing the time the application entered this stage. - `applicationHistoryId` string, uuid, nullable — The id of the application history event to update. Required when updating an existing event; omit for new events. - `archiveReasonId` string, uuid, nullable — The id of the archive reason. Required when the interview stage is of type `Archived`. ## Response `200` Responses from the application.updateHistory endpoint - union - ApplicationUpdateHistorySuccessResponse - `success` true, required - `results` ApplicationUpdateHistoryResult, required - `id` string, uuid, required — The unique identifier for the application - `createdAt` string, date-time, required — The timestamp when the application was created - `updatedAt` string, date-time, required — The timestamp when the application was last updated - `status` 'Hired' | 'Archived' | 'Active' | 'Lead', required — The status of the application - `customFields` object[], nullable — Custom fields attached to the application, if any - `id` string, uuid, required — The unique identifier for the custom field definition - `isPrivate` boolean — Whether the custom field is private - `title` string, required — The title of the custom field - `valueLabel` union — The human-readable label for select custom field values - string - string[] - `value` union, required — The custom field value - boolean - number - string - string[] - object - `value` number, required — The currency amount - `currencyCode` string, required — The ISO currency code - object - `type` string, required — The range type - `minValue` number, required — The minimum value - `maxValue` number, required — The maximum value - object - `type` string, required — The compensation range type - `minValue` number, required — The minimum compensation value - `maxValue` number, required — The maximum compensation value - `currencyCode` string, required — The ISO currency code - `interval` string, required — The compensation interval - `candidate` object, required — The candidate associated with the application - `id` string, uuid, required — The unique identifier for the candidate - `name` string, required — The candidate's name - `primaryEmailAddress` object, nullable — The candidate's primary email address, if any - `value` string, required — The email address or phone number of the candidate - `type` 'Personal' | 'Work' | 'Other', required — The type of the contact info - `isPrimary` boolean, required — Whether the contact info is the primary email or phone number - `primaryPhoneNumber` object, nullable — The candidate's primary phone number, if any - `value` string, required — The email address or phone number of the candidate - `type` 'Personal' | 'Work' | 'Other', required — The type of the contact info - `isPrimary` boolean, required — Whether the contact info is the primary email or phone number - `currentInterviewStage` object, required — The current interview stage for the application - `id` string, uuid, required — The unique identifier for the interview stage - `title` string, required — The interview stage title - `type` string, required — The interview stage type - `orderInInterviewPlan` integer, required — The stage's order within its interview plan - `interviewStageGroupId` string, uuid, nullable — The id of the interview stage group the stage belongs to, if any - `interviewPlanId` string, uuid, required — The id of the interview plan the stage belongs to - `source` object, nullable — The source attributed to this application, if any - `id` string, uuid, required — The source's unique identifier - `title` string, required — The title of the source - `isArchived` boolean, required — Whether the source has been archived - `sourceType` object, required — The source type associated with this source - `id` string, uuid, required — The source type's unique identifier - `title` string, required — The title of the source type - `isArchived` boolean, required — Whether the source type has been archived - `archiveReason` object, nullable — Details about the archive reason for this application, if archived - `id` string, uuid, required — The unique identifier for the archive reason - `text` string, required — The display text for the archive reason - `reasonType` 'RejectedByCandidate' | 'RejectedByOrg' | 'Other', required — The category of archive reason - `isArchived` boolean, required — Whether the archive reason is archived - `customFields` object[], required — Archive detail custom field values - `id` string, uuid, required — The unique identifier for the custom field definition - `isPrivate` boolean — Whether the custom field is private - `title` string, required — The title of the custom field - `valueLabel` union — The human-readable label for select custom field values - string - string[] - `value` union, required — The custom field value - boolean - number - string - string[] - object - … - object - … - object - … - `archivedAt` string, date-time, nullable — The timestamp an application was archived - `job` object, required — The job the application is for - `id` string, uuid, required — The unique identifier for the job - `title` string, required — The job title - `locationId` string, uuid, nullable — The id of the job's primary location, if any - `departmentId` string, uuid, nullable — The id of the job's department, if any - `creditedToUser` User - `id` string, uuid, required — The unique identifier for the user - `firstName` string, required — The user's first name - `lastName` string, required — The user's last name - `email` string, email, nullable, required — The user's email address - `globalRole` 'Organization Admin' | 'Elevated Access' | 'Limited Access' | 'External Recruiter', required — The user's global role in the organization - `isEnabled` boolean, required — Whether the user is enabled (not deactivated) - `updatedAt` string, required — The timestamp when the user was last updated (ISO 8601 format) - `managerId` string, uuid — The unique identifier for the user's manager - `customFields` CustomField[] — Custom fields associated with the user (only included when requested) - `id` string, uuid, required — The unique identifier for the custom field definition - `isPrivate` boolean, required — Whether the custom field is private - `title` string, required — The title of the custom field - `value` union, required — The value of the custom field - boolean - number - string - string[] - object - … - object - … - object - … - object - … - `valueLabel` union — The label of the custom field value. This is only present for value select custom fields. - string - string[] - `hiringTeam` HiringTeamRole[], required — The hiring team for the application - `userId` string, uuid, required — The unique identifier of the hiring team member - `firstName` string, required — The first name of the hiring team member - `lastName` string, required — The last name of the hiring team member - `email` string, email, required — The primary email address of the hiring team member - `role` string, required — The hiring team role assigned to the member - `appliedViaJobPostingId` string, uuid, nullable — The id of the first job posting the candidate applied through. If the candidate submitted applications via multiple job postings for the same job, this will be the earliest one. - `submitterClientIp` string, nullable — The IP address (can be v4 or v6) of the client that submitted the application, if it was submitted through the external job board. - `submitterUserAgent` string, nullable — The user agent of the client that submitted the application, if it was submitted through the external job board. - `openings` object[], nullable — The openings linked to the application. Only included when the request was made with `expand: ['openings']`. - `id` string, uuid, required — The unique identifier for the opening - `openedAt` string, date-time, nullable — The timestamp the opening was opened - `closedAt` string, date-time, nullable — The timestamp the opening was closed - `isArchived` boolean, required — Whether the opening is archived - `archivedAt` string, date-time, nullable — The timestamp the opening was archived - `closeReasonId` string, uuid, nullable — The unique identifier for the close reason - `openingState` 'Approved' | 'Closed' | 'Draft' | 'Filled' | 'Open', required — The current state of the opening - `latestVersion` object, nullable — The latest version of the opening - `id` string, uuid, required — The unique identifier for the opening version - `identifier` string, required — The human-readable opening identifier - `description` string, nullable, required — The opening description - `authorId` string, uuid, nullable, required — The unique identifier for the author - `createdAt` string, date-time, required — The timestamp when the opening version was created - `teamId` string, uuid, nullable — The unique identifier for the team - `jobIds` string[], required — The unique identifiers for jobs linked to the opening - `targetHireDate` string, nullable — The target hire date - `targetStartDate` string, nullable — The target start date - `isBackfill` boolean, required — Whether the opening is a backfill - `employmentType` string, required — The employment type - `locationIds` string[], required — The location ids - `hiringTeam` object[], required — Hiring team for the opening - `userId` string, uuid, required — The user id - `firstName` string, required — The first name - `lastName` string, required — The last name - `email` string, email, required — The email - `role` string, required — The role - `customFields` object[], required — Custom fields attached to the opening - `id` string, uuid, required — The unique identifier for the custom field definition - `isPrivate` boolean — Whether the custom field is private - `title` string, required — The title of the custom field - `valueLabel` union — The human-readable label for select custom field values - … - `value` union, required — The custom field value - … - `applicationHistory` ApplicationHistory[], nullable — The application's history events. - `id` string, uuid, required — The unique identifier for the history event - `stageId` string, uuid, required — The id of the interview stage for this event - `title` string, required — The interview stage title for this event - `enteredStageAt` string, date-time, required — The timestamp the application entered this stage - `leftStageAt` string, date-time, nullable — The timestamp the application left this stage, if any - `stageNumber` integer, required — The order of the history event in the application's history. 0 is the first event. - `allowedActions` string[], required — Actions that can be performed on this history event via `application.updateHistory`. - `actorId` string, uuid, nullable — The ID of the user that performed the stage change, if any. - `applicationFormSubmissions` object[], nullable — Application form submissions. These match the response from the `applicationForm.submit` endpoint. Only included when the request was made with `expand: ['applicationFormSubmissions']`. - `id` string, uuid, required — The unique identifier for the application form submission - `formDefinition` FormDefinition, required - `sections` FormDefinitionSection[], required — The sections in the form definition - `title` string, nullable — The section title - `descriptionHtml` string, nullable — The section description formatted as HTML - `descriptionPlain` string, nullable — The section description as plain text - `fields` FormDefinitionFieldEntry[], required — The fields in this form section - … - `submittedValues` unknown, required - `referrals` object[], nullable — Referrals for the application. Only included when the request was made with `expand: ['referrals']`. - `user` User, required - `id` string, uuid, required — The unique identifier for the user - `firstName` string, required — The user's first name - `lastName` string, required — The user's last name - `email` string, email, nullable, required — The user's email address - `globalRole` 'Organization Admin' | 'Elevated Access' | 'Limited Access' | 'External Recruiter', required — The user's global role in the organization - `isEnabled` boolean, required — Whether the user is enabled (not deactivated) - `updatedAt` string, required — The timestamp when the user was last updated (ISO 8601 format) - `managerId` string, uuid — The unique identifier for the user's manager - `customFields` CustomField[] — Custom fields associated with the user (only included when requested) - `id` string, uuid, required — The unique identifier for the custom field definition - `isPrivate` boolean, required — Whether the custom field is private - `title` string, required — The title of the custom field - `value` union, required — The value of the custom field - … - `valueLabel` union — The label of the custom field value. This is only present for value select custom fields. - … - `referredAt` string, date-time, required — The timestamp the referral was created - ErrorResponse - `success` false, required - `errors` ErrorDetail[], required - `message` string, required - `parameter` string --- [API](https://skmtc.net/ashbyhq/apis/ashby-api.md) · [All operations](https://skmtc.net/ashbyhq/apis/ashby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ashbyhq/ashby-api/revisions/778b919dc743/schema)