> ## Documentation Index > Fetch the complete documentation index at: https://developer.vanta.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert a control's assessment within an audit > Records (upserts) an auditor's assessment state and justification for a control within an IRL audit — the API equivalent of assessing a control in the web app. Overwrites the single assessment for this control in the audit's program segment. The `assessmentState` must be valid for the audit's framework (the request is rejected otherwise). The acting auditor is identified by `auditorEmail`, which must belong to the audit firm making the request. Returns 404 when the control is not part of the audit or the auditor email does not resolve to a firm user. Applies to both Full and Controlled Audit View audits. Rate limit: 10 requests / minute. ## OpenAPI ````yaml https://spec.speakeasy.com/vanta/vanta/conduct-an-audit-with-code-samples put /audits/{auditId}/controls/{controlId}/assessment openapi: 3.0.0 info: title: Conduct an audit version: 1.0.0 description: >- The Auditor API lets audit firms conduct audits from a tool outside of Vanta. Unlock data syncing with Vanta through this API. **Note for Vanta Gov (FedRAMP) customers:** Select `Vanta Gov (FedRAMP)` from the server dropdown to issue requests against `https://api.vanta-gov.com`. The OAuth token URL shown below defaults to the commercial host — replace it with `https://api.vanta-gov.com/oauth/token`. termsOfService: https://www.vanta.com/terms license: name: UNLICENSED contact: name: API Support url: https://help.vanta.com/ email: support@vanta.com servers: - url: https://api.vanta.com/v1 description: US Region API - url: https://api.vanta-gov.com/v1 description: Vanta Gov (FedRAMP) security: [] paths: /audits/{auditId}/controls/{controlId}/assessment: put: tags: - Audits summary: Upsert a control's assessment within an audit description: >- Records (upserts) an auditor's assessment state and justification for a control within an IRL audit — the API equivalent of assessing a control in the web app. Overwrites the single assessment for this control in the audit's program segment. The `assessmentState` must be valid for the audit's framework (the request is rejected otherwise). The acting auditor is identified by `auditorEmail`, which must belong to the audit firm making the request. Returns 404 when the control is not part of the audit or the auditor email does not resolve to a firm user. Applies to both Full and Controlled Audit View audits. Rate limit: 10 requests / minute. operationId: UpsertAssessmentForControl parameters: - in: path name: auditId required: true schema: type: string - in: path name: controlId required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertAuditControlAssessmentInput' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/AuditorControlAssessment' examples: Example 1: value: controlId: a2f7e1b9d0c3f4e5a6c7b8d9 assessmentState: IN_PLACE justification: >- Encryption at rest and in transit verified via cloud configuration evidence. security: - bearerAuth: [] x-codeSamples: - lang: typescript label: UpsertAssessmentForControl source: |- import { Vanta } from "vanta-auditor-api-sdk"; const vanta = new Vanta({ bearerAuth: process.env["VANTA_BEARER_AUTH"] ?? "", }); async function run() { const result = await vanta.audits.upsertAssessmentForControl({ auditId: "", controlId: "", upsertAuditControlAssessmentInput: { assessmentState: "TRUE", justification: "", auditorEmail: "", }, }); console.log(result); } run(); - lang: java label: UpsertAssessmentForControl source: >- package hello.world; import com.vanta.vanta_auditor_api.Vanta; import com.vanta.vanta_auditor_api.models.components.AuditControlAssessmentState; import com.vanta.vanta_auditor_api.models.components.UpsertAuditControlAssessmentInput; import com.vanta.vanta_auditor_api.models.operations.UpsertAssessmentForControlResponse; import java.lang.Exception; public class Application { public static void main(String[] args) throws Exception { Vanta sdk = Vanta.builder() .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", "")) .build(); UpsertAssessmentForControlResponse res = sdk.audits().upsertAssessmentForControl() .auditId("") .controlId("") .upsertAuditControlAssessmentInput(UpsertAuditControlAssessmentInput.builder() .assessmentState(AuditControlAssessmentState.TRUE) .justification("") .auditorEmail("") .build()) .call(); if (res.auditorControlAssessment().isPresent()) { System.out.println(res.auditorControlAssessment().get()); } } } components: schemas: UpsertAuditControlAssessmentInput: description: >- Input for upserting a control's auditor assessment within an audit. Overwrites the single assessment for this control in the audit's program segment. properties: assessmentState: $ref: '#/components/schemas/AuditControlAssessmentState' description: >- The assessment state to record. Must be one of the states valid for the audit's framework; the request is rejected otherwise. justification: type: string description: >- Free-text reasoning for the assessment. Required, and at most 5000 characters. auditorEmail: type: string description: >- Email of the auditor performing the assessment. Must match an existing Vanta user who belongs to the audit firm making the API request. required: - assessmentState - justification - auditorEmail type: object additionalProperties: false AuditorControlAssessment: description: |- A control's auditor assessment, as persisted. Returned by the assessment write endpoint so the caller sees exactly what was recorded. properties: controlId: type: string description: The control this assessment belongs to. assessmentState: $ref: '#/components/schemas/AuditControlAssessmentState' description: The recorded assessment state. justification: type: string description: The recorded justification. required: - controlId - assessmentState - justification type: object additionalProperties: false AuditControlAssessmentState: type: string enum: - IN_PLACE - NOT_IN_PLACE - PARTIAL - NOT_ASSESSED - CONFORMING - MINOR_NON_CONFORMITY - MAJOR_NON_CONFORMITY - SATISFIED - NOT_SATISFIED - OTHER_THAN_SATISFIED - 'TRUE' - 'FALSE' description: >- An auditor's assessment of a control within an audit. This is the full flat union of every framework's assessment states (the superset); a given audit's framework only uses its own subset. `NOT_ASSESSED` is shared by all frameworks and is the default for a control that has not yet been assessed. Which states apply to which framework: - Most frameworks (e.g. SOC 2): `IN_PLACE`, `NOT_IN_PLACE`, `PARTIAL`, `NOT_ASSESSED` - ISO 27001: `CONFORMING`, `MINOR_NON_CONFORMITY`, `MAJOR_NON_CONFORMITY`, `NOT_ASSESSED` - FedRAMP: `SATISFIED`, `NOT_SATISFIED`, `OTHER_THAN_SATISFIED`, `NOT_ASSESSED` - FedRAMP Key Security Indicators (KSI): `TRUE`, `FALSE`, `PARTIAL`, `NOT_ASSESSED` Distinct from `ControlStatus`, which is the computed tests/documents-passing status — a different concept. securitySchemes: bearerAuth: type: http scheme: bearer ````