> ## 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. # Start assessment > Starts an assessment for the specified vendor and assessment type. Creates an assessment if needed, or starts an eligible existing assessment. Assessments associated with security incidents cannot be started through this endpoint. Requires both the `vendors:view` and `vendors_data:manage` organization permissions: `vendors:view` to read the assessment type and `vendors_data:manage` to start the assessment. Returns 403 Forbidden when the caller lacks either permission. Returns 404 Not Found when the vendor or the assessment type does not exist in the customer's organization. Returns 422 Unprocessable Entity when an eligible assessment cannot be started, including when it is already in progress. ## OpenAPI ````yaml /reference/manage-vanta.json post /vendors/{vendorId}/assessments openapi: 3.0.0 info: title: Manage Vanta version: 1.0.0 description: >- The REST API lets customers query and mutate Vanta's data. Use this API to automate bulk actions, query data for custom workflows and dashboards, and bolster your security operations **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: Vanta (Commercial) - url: https://api.vanta-gov.com/v1 description: Vanta Gov (FedRAMP) security: [] paths: /vendors/{vendorId}/assessments: post: tags: - Vendors summary: Start assessment description: >- Starts an assessment for the specified vendor and assessment type. Creates an assessment if needed, or starts an eligible existing assessment. Assessments associated with security incidents cannot be started through this endpoint. Requires both the `vendors:view` and `vendors_data:manage` organization permissions: `vendors:view` to read the assessment type and `vendors_data:manage` to start the assessment. Returns 403 Forbidden when the caller lacks either permission. Returns 404 Not Found when the vendor or the assessment type does not exist in the customer's organization. Returns 422 Unprocessable Entity when an eligible assessment cannot be started, including when it is already in progress. operationId: StartAssessmentForVendor parameters: - in: path name: vendorId required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartVendorAssessmentInput' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/VendorAssessment' examples: Example 1: value: id: a2f7e1b9d0c3f4e5a6c7b8d8 vendorId: 6696e9bca247cbdf1c8e5054 status: COMPLETED audience: EXTERNAL completedByUserId: 6696ea0595df50d5cd6ec3b7 startDate: '2024-02-01T00:00:00.000Z' dueDate: '2024-03-01T00:00:00.000Z' overrideDueDate: '2024-03-15T00:00:00.000Z' completionDate: '2024-03-10T00:00:00.000Z' createdDate: '2024-01-25T00:00:00.000Z' decision: status: APPROVED lastUpdatedAt: '2024-03-17T00:00:00.000Z' comments: >- No major concerns, limited sharing of data, low security risk. assessmentType: id: 6696ea0595df50d5cd6ec3b8 name: Security description: null owner: id: 6696ea0595df50d5cd6ec3b9 type: USER displayName: Jane Doe email: jane.doe@example.com security: - bearerAuth: [] components: schemas: StartVendorAssessmentInput: properties: assessmentTypeId: type: string description: ID of the assessment type to start for this vendor. pattern: ^[0-9a-fA-F]{24}$ required: - assessmentTypeId type: object additionalProperties: false VendorAssessment: properties: id: type: string description: Unique identifier for the assessment. vendorId: type: string description: Unique identifier for the vendor. status: $ref: '#/components/schemas/AssessmentStatus' description: The lifecycle status of the assessment. audience: $ref: '#/components/schemas/VendorAssessmentTypeAudience' description: Who fills out this assessment. completedByUserId: type: string nullable: true description: The Vanta user ID of the person who completed this assessment. startDate: type: string format: date-time nullable: true description: The timestamp of when the assessment was started. dueDate: type: string format: date-time nullable: true description: The timestamp of when the assessment is due. overrideDueDate: type: string format: date-time nullable: true description: A manual override timestamp of when the assessment is due. completionDate: type: string format: date-time nullable: true description: The timestamp of when the assessment was marked as completed. createdDate: type: string format: date-time description: The timestamp of when the assessment was created. decision: properties: comments: type: string nullable: true description: Comments about the assessment decision. lastUpdatedAt: type: string format: date-time description: The timestamp of when the assessment decision was last set. status: $ref: '#/components/schemas/AssessmentDecision' description: The status of the current decision. required: - comments - lastUpdatedAt - status type: object nullable: true description: >- An object containing information about the decision of the assessment. assessmentType: $ref: '#/components/schemas/AssessmentType' description: The assessment type for this assessment. owner: allOf: - $ref: '#/components/schemas/AssessmentOwner' nullable: true description: The owner of this assessment, if assigned. required: - id - vendorId - status - audience - completedByUserId - startDate - dueDate - overrideDueDate - completionDate - createdDate - decision - assessmentType - owner type: object additionalProperties: false AssessmentStatus: description: |- The lifecycle status of an assessment: - NOT_STARTED: The assessment has not yet been started. - IN_PROGRESS: The assessment is underway. - COMPLETED: The assessment has been completed. enum: - NOT_STARTED - IN_PROGRESS - COMPLETED type: string VendorAssessmentTypeAudience: description: |- Who fills out a vendor assessment: - EXTERNAL: The vendor fills out the assessment. - INTERNAL: The organization's own employees fill out the assessment. enum: - EXTERNAL - INTERNAL type: string AssessmentDecision: description: >- The current decision made for an assessment: - APPROVED: The assessment has been approved. - NOT_APPROVED: The assessment has been marked not approved. - CONDITIONALLY_APPROVED: The assessment has been conditionally approved. enum: - APPROVED - NOT_APPROVED - CONDITIONALLY_APPROVED type: string AssessmentType: properties: id: type: string description: Unique identifier for the assessment type. name: type: string description: Display name of the assessment type. description: type: string nullable: true description: Description of the assessment type, if set. required: - id - name - description type: object additionalProperties: false AssessmentOwner: properties: id: type: string description: Unique identifier for the owner. type: $ref: '#/components/schemas/AssessmentOwnerType' description: The type of actor that owns this assessment. displayName: type: string nullable: true description: Display name of the owner, if available. email: type: string nullable: true description: Email of the owner. Populated for USER owners, null for TEAM owners. required: - id - type - displayName - email type: object additionalProperties: false AssessmentOwnerType: type: string enum: - USER - TEAM securitySchemes: bearerAuth: type: http scheme: bearer ```` ## Related topics - [List assessment types](https://developer.vanta.com/api-reference/vendor-assessment-types/list-assessment-types.md) - [List assessments by vendor ID](https://developer.vanta.com/api-reference/vendors/list-assessments-by-vendor-id.md) - [Get assessment by ID](https://developer.vanta.com/api-reference/vendors/get-assessment-by-id.md) - [List security reviews by vendor ID](https://developer.vanta.com/api-reference/vendors/list-security-reviews-by-vendor-id.md) - [Add document to assessment](https://developer.vanta.com/api-reference/vendors/add-document-to-assessment.md)