Conduct an Audit via API

Learn how to register an auditor application, authenticate with auditor scopes, and pull information requests from one of your active audits.

By the end of this quickstart you’ll have a working auditor access token and you’ll have used it to list the information requests for one of your active audits.

Before you begin

Make sure you have:

• An active Vanta Audit Partner registration. If you don’t see the Auditor API option in your Vanta navigation, contact your Vanta representative.
• An auditor login at Vanta app.
• At least one active audit assigned to your firm — most endpoints return data only for audits that already exist.
• A terminal or HTTP client (cURL, Postman, or your language of choice).

This quickstart is for Vanta audit partners pulling data from their customers’ audits. If you’re a Vanta customer automating your own tenant, see the Manage Vanta quickstart. If you’re a partner building a public integration, see the Build an Integration quickstart.

1. Create an auditor application

   Vanta Dashboard — sign in to Vanta app with your auditor email. In the left navigation, open Auditor API, then click Create.

   

   Give your application a name and description, then click Create.

   

   The OAuth client_id is auto-generated. Click Generate client secret to create the secret. Store both values securely — only share with trusted team members. You can rotate the secret at any time.

   
2. Get an access token

   From your terminal, exchange your client credentials for an access token. This quickstart only makes read calls, so request the minimum scope: auditor-api.audit:read.

   Terminal

   curl --location 'https://api.vanta.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '{
       "client_id": "your_client_id",
       "client_secret": "your_client_secret",
       "scope": "auditor-api.audit:read",
       "grant_type": "client_credentials"
     }'
   

   Expected response:

   {
     "access_token": "vat_your_token",
     "expires_in": 3599,
     "token_type": "Bearer"
   }
   

   One token at a time. Vanta only allows one active access token per application — requesting a new token immediately revokes the previous one. Tokens expire after one hour.

   Got a 401 or invalid_client?

   Double-check the client_id and client_secret from the Auditor API page. If you rotated the secret, the old one is no longer valid. Make sure your Content-Type header is application/json — Vanta’s /oauth/token does not accept form-encoded bodies.

   Got an invalid_scope error?

   You requested a scope that isn’t available to Auditor apps. For this quickstart, request only auditor-api.audit:read. Auditor apps can also request auditor-api.audit:write, auditor-api.auditor:read, and auditor-api.auditor:write — request only what your tool needs.

3. List your active audits

   From your terminal, call GET /v1/audits to see the audits assigned to your firm, then grab an auditId to use in the next step. Pass isActiveAudit=true to filter out audits with a final report already uploaded. Replace your_token_here with the access_token from Step 2.

   Terminal

   curl --location 'https://api.vanta.com/v1/audits?isActiveAudit=true&pageSize=10' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer your_token_here'
   

   Expected response — note the id field on each audit; that’s the auditId you’ll use in the next step:

   {
     "results": {
       "data": [
         {
           "id": "65fc81a3359c8508c9af880f",
           "customerOrganizationName": "corporation.com",
           "customerDisplayName": "Corporation Company",
           "customerOrganizationId": "65fc81a3359c8508c9af880f",
           "auditStartDate": "2024-03-07T21:25:56.000Z",
           "auditEndDate": "2024-03-14T21:25:56.000Z",
           "framework": "SOC 2 Type II",
           "displayName": "Q1 2024 SOC 2 Audit",
           "auditFocus": "EXTERNAL"
         }
       ],
       "pageInfo": {
         "hasNextPage": false,
         "hasPreviousPage": false,
         "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
         "endCursor": "YXJyYXljb25uZWN0aW9uOjE="
       }
     }
   }
   

   Empty `data` array?

   Either your firm has no active audits in flight, or every audit already has a final report uploaded (filtered out by isActiveAudit=true). Re-run the request without isActiveAudit=true to include completed audits.

4. List information requests for that audit

   From your terminal, call GET /v1/audits/{auditId}/information-requests with the auditId from Step 3. This returns every information request (IR) on the audit — the evidence requirements your team and the customer are working through. Reuse the same access_token from Step 2 by replacing your_token_here.

   Terminal

   curl --location 'https://api.vanta.com/v1/audits/65fc81a3359c8508c9af880f/information-requests?pageSize=10' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer your_token_here'
   

   Expected response:

   {
     "results": {
       "data": [
         {
           "id": "6890e473dce1da5d8406f5e7",
           "uniqueId": "1466132",
           "title": "Terminated Customer Deletion Evidence",
           "description": "Provide the data deletion evidence for a sample of terminated customers",
           "approvalStatus": "NEEDS_EVIDENCE",
           "cadence": "ANNUALLY",
           "frameworkCodes": ["SOC2_CC6.1"],
           "requestType": "SAMPLE",
           "dueDate": "2025-10-28T00:00:00.000Z",
           "ownerAssignment": {
             "type": "user",
             "id": "507f1f77bcf86cd799439011",
             "displayName": "John Doe"
           },
           "creationDate": "2025-08-01T12:34:56.000Z",
           "modificationDate": "2025-08-02T08:00:00.000Z",
           "deletionDate": null
         }
       ],
       "pageInfo": {
         "hasNextPage": false,
         "hasPreviousPage": false,
         "startCursor": "Njg5MGU0NzNkY2UxZGE1Z",
         "endCursor": "Njg5MGU0NzNkY2UxZGE1Z"
       }
     }
   }
   

   Empty `data` array?

   Either the audit has no information requests yet, or the requests haven’t been shared with the customer. Confirm in the Vanta dashboard that the audit has IRs configured. Note that this endpoint always includes soft-deleted records — check deletionDate to skip them.

   Got a 403 Forbidden?

   Your firm isn’t assigned to this audit, or your application’s allowlisted auditor emails don’t include you. Re-run Step 3 and copy an auditId from the response — that list is already scoped to audits your firm can see.

5. Verify it worked

   Pick an information request from the response and open the audit in Vanta app — find the IR by its uniqueId or title. You should land on the same record the API just returned.

   Confirm on the dashboard:

   • The title, description, and due date match what the API returned.
   • The approval status matches approvalStatus from the response (e.g. NEEDS_EVIDENCE, AWAITING_REVIEW, APPROVED).
   • The owner matches ownerAssignment.displayName.

   Scenario	Test input	Expected result
   Success	An IR with approvalStatus: "NEEDS_EVIDENCE" from the response	The IR exists in the dashboard with matching title, description, and due date; status reads “Needs evidence”
   Auth failure	Expired access_token (older than one hour)	401 Unauthorized — re-run Step 2 for a fresh token
   Edge case	An IR with a non-null deletionDate	Record is soft-deleted; it won’t appear in the dashboard, and your tool should skip or archive it

Congratulations

You have a working auditor token and you’ve used it to read information requests from one of your active audits. From here you can:

• Pull the controls for an audit with GET /v1/audits/{auditId}/controls to see every requirement in scope.
• Pull evidence with GET /v1/audits/{auditId}/evidence to feed the customer’s evidence into your audit-management tooling.
• Create custom IRs with POST /v1/audits/{auditId}/information-requests to add evidence requirements that supplement Vanta’s built-in scaffolding (requires the auditor-api.audit:write scope).
• Accept or flag evidence on an IR programmatically once your team has reviewed it.

Next steps

List audit controls

Pull every control in scope for an audit, with framework codes and status.

Manage information requests

Create custom IRs, accept or flag evidence, and share the IR list with the customer.

Browse the Auditor API

Every endpoint available to auditor apps.

Set up Postman

Import the Vanta collection and start testing requests in seconds.