> ## 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.

# List people for an audit

> Retrieves people population data for an audit.

This endpoint provides access to the people records visible to auditors
during an audit engagement. Only Controlled Audit View (CAV) audits
are supported. Full Audit View audits are rejected with 403.

Supports filtering by:
- `search`: Searches names and email addresses
- `status`: Filters by employment status
- `groupsMatchesAny`: Filter people by group/role IDs

Results are sorted by name (ascending) by default.
Use `orderBy` and `orderDirection` to customize sorting.
Sort parameters must remain consistent across paginated requests.

Uses cursor-based pagination. To paginate:
1. Make initial request with desired `pageSize`
2. Check `results.pageInfo.hasNextPage`
3. Use `results.pageInfo.endCursor` as `pageCursor` for next request

Rate limit: 10 requests / minute.



## OpenAPI

````yaml https://spec.speakeasy.com/vanta/vanta/conduct-an-audit-with-code-samples get /audits/{auditId}/personnel/people
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}/personnel/people:
    get:
      tags:
        - Audits
      summary: List people for an audit
      description: |-
        Retrieves people population data for an audit.

        This endpoint provides access to the people records visible to auditors
        during an audit engagement. Only Controlled Audit View (CAV) audits
        are supported. Full Audit View audits are rejected with 403.

        Supports filtering by:
        - `search`: Searches names and email addresses
        - `status`: Filters by employment status
        - `groupsMatchesAny`: Filter people by group/role IDs

        Results are sorted by name (ascending) by default.
        Use `orderBy` and `orderDirection` to customize sorting.
        Sort parameters must remain consistent across paginated requests.

        Uses cursor-based pagination. To paginate:
        1. Make initial request with desired `pageSize`
        2. Check `results.pageInfo.hasNextPage`
        3. Use `results.pageInfo.endCursor` as `pageCursor` for next request

        Rate limit: 10 requests / minute.
      operationId: ListPersonnelPeople
      parameters:
        - description: The audit ID
          in: path
          name: auditId
          required: true
          schema:
            type: string
        - description: Maximum number of results per page (1-100, default 10)
          in: query
          name: pageSize
          required: false
          schema:
            $ref: '#/components/schemas/PageSize'
        - description: Pagination cursor from previous response
          in: query
          name: pageCursor
          required: false
          schema:
            $ref: '#/components/schemas/PageCursor'
        - description: Search term for filtering by name or email
          in: query
          name: search
          required: false
          schema:
            type: string
        - description: Employment status filter
          in: query
          name: status
          required: false
          schema:
            $ref: '#/components/schemas/PeopleEmploymentStatus'
        - description: Filter people by group IDs
          in: query
          name: groupsMatchesAny
          required: false
          schema:
            items:
              type: string
            type: array
        - description: >-
            Field to sort results by. Allowed: "name", "employmentStatus".
            Default: "name"
          in: query
          name: orderBy
          required: false
          schema:
            $ref: '#/components/schemas/PeopleOrderBy'
        - description: 'Sort direction: "asc" or "desc". Default: "asc"'
          in: query
          name: orderDirection
          required: false
          schema:
            $ref: '#/components/schemas/OrderDirection'
      responses:
        '200':
          description: Paginated list of people with pagination metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_PersonnelPerson_'
              examples:
                Example 1:
                  value:
                    results:
                      pageInfo:
                        hasNextPage: true
                        hasPreviousPage: false
                        startCursor: person_12345
                        endCursor: person_12345
                      data:
                        - id: person_12345
                          name: John Doe
                          email: john.doe@example.com
                          jobTitle: Software Engineer
                          employmentStatus: CURRENTLY_EMPLOYED
                          startDate: '2021-01-15'
                          endDate: null
                          groups:
                            - name: Engineering
                            - name: Admin
                          source:
                            mainSource: Okta
                            supplementarySource: Google Workspace
                          taskStatus:
                            status: SECURITY_TASKS_COMPLETE
                            dueDate: '2024-03-15'
                            completionDate: '2024-01-20'
                            numTasksCompleted: null
                            numTasksOverdue: null
                            numTasksDueSoon: null
                          lastReminded: '2024-01-15'
                          policies:
                            status: SECURITY_TASKS_COMPLETE
                            dueDate: '2024-03-15'
                            completionDate: '2024-01-20'
                          trainings:
                            status: SECURITY_TASKS_COMPLETE
                            dueDate: '2024-03-15'
                            completionDate: '2024-01-20'
                          backgroundChecks:
                            status: SECURITY_TASKS_COMPLETE
                            dueDate: '2024-03-15'
                            completionDate: '2024-01-20'
                          deviceMonitoring:
                            status: SECURITY_TASKS_COMPLETE
                            dueDate: '2024-03-15'
                            completionDate: '2024-01-20'
                          customOnboarding:
                            status: SECURITY_TASKS_COMPLETE
                            dueDate: '2024-03-15'
                            completionDate: '2024-01-20'
                          customOffboarding:
                            status: SECURITY_TASKS_COMPLETE
                            dueDate: '2024-03-15'
                            completionDate: '2024-01-20'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: typescript
          label: ListPersonnelPeople
          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.listPersonnelPeople({
                auditId: "<id>",
              });

              console.log(result);
            }

            run();
        - lang: java
          label: ListPersonnelPeople
          source: >-
            package hello.world;


            import com.vanta.vanta_auditor_api.Vanta;

            import
            com.vanta.vanta_auditor_api.models.operations.ListPersonnelPeopleRequest;

            import
            com.vanta.vanta_auditor_api.models.operations.ListPersonnelPeopleResponse;

            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();

                    ListPersonnelPeopleRequest req = ListPersonnelPeopleRequest.builder()
                            .auditId("<id>")
                            .build();

                    ListPersonnelPeopleResponse res = sdk.audits().listPersonnelPeople()
                            .request(req)
                            .call();

                    if (res.paginatedResponsePersonnelPerson().isPresent()) {
                        System.out.println(res.paginatedResponsePersonnelPerson().get());
                    }
                }
            }
components:
  schemas:
    PageSize:
      type: integer
      format: int32
      default: 10
      description: >-
        Controls the maximum number of items returned in one response from the
        API.
      minimum: 1
      maximum: 100
    PageCursor:
      type: string
      description: >-
        A marker or pointer, telling the API where to start fetching items for
        the subsequent page in a paginated dataset.

        Note that the requested page will not include the item that corresponds
        to this cursor but will start from the one immediately

        after this cursor.
    PeopleEmploymentStatus:
      type: string
      enum:
        - CURRENTLY_EMPLOYED
        - INACTIVE_EMPLOYEE
        - NOT_PEOPLE
        - ON_LEAVE
        - PREVIOUSLY_EMPLOYED
        - UPCOMING_EMPLOYEE
      description: Employment status filter for people queries.
    PeopleOrderBy:
      type: string
      enum:
        - name
        - employmentStatus
    OrderDirection:
      type: string
      enum:
        - asc
        - desc
      description: >-
        Sort direction shared across the external REST API surface.


        `"asc"` for ascending, `"desc"` for descending. Endpoints expose this as
        the

        `orderDirection` / `sortDirection` query parameter and map it onto
        whatever

        internal direction representation the underlying service expects.
    PaginatedResponse_PersonnelPerson_:
      properties:
        results:
          properties:
            data:
              items:
                $ref: '#/components/schemas/PersonnelPerson'
              type: array
            pageInfo:
              $ref: '#/components/schemas/PageInfo'
          required:
            - data
            - pageInfo
          type: object
      required:
        - results
      type: object
      additionalProperties: false
    PersonnelPerson:
      description: >-
        Personnel person data.


        `id`, `name`, and `email` are required. All other fields are optional to
        support customizable field visibility.


        Omitted keys mean the column is not in the response; `null` means the
        column is present but empty.
      properties:
        id:
          type: string
          description: User ID - always present.
          example: 5f2c939a52855e725c8d5824
        name:
          type: string
          description: Display name of the person - always present.
          example: John Doe
        email:
          type: string
          description: Email address of the person - always present.
          example: john.doe@example.com
        jobTitle:
          type: string
          nullable: true
          description: Job title from HR system, or null if not available.
          example: Software Engineer
        employmentStatus:
          allOf:
            - $ref: '#/components/schemas/PeopleEmploymentStatus'
          nullable: true
          description: Employment status, or null if not available.
          example: CURRENTLY_EMPLOYED
        startDate:
          type: string
          nullable: true
          description: >-
            Start date in ISO 8601 format (YYYY-MM-DD), or null if not
            available.

            Timezone depends on source: UTC if from HR system,

            customer timezone if manually entered.
          example: '2021-01-15'
        endDate:
          type: string
          nullable: true
          description: >-
            End date in ISO 8601 format (YYYY-MM-DD), or null if currently
            employed.
          example: '2021-01-15'
        groups:
          items:
            properties:
              name:
                type: string
            required:
              - name
            type: object
          type: array
          description: >-
            Groups (roles) the person belongs to. Present only when the column
            is in the response;

            use an empty array when there are no groups.
          example:
            - name: Engineering
            - name: Admin
        source:
          allOf:
            - $ref: '#/components/schemas/PeopleSourceInfo'
          nullable: true
          description: |-
            Source of user data, or null if not available.
            Full Audit View only - omitted in Controlled Audit View.
        taskStatus:
          allOf:
            - $ref: '#/components/schemas/PeopleTaskStatusInfo'
          nullable: true
          description: |-
            Overall task status information, or null if not available.
            Full Audit View only - omitted in Controlled Audit View.
        lastReminded:
          type: string
          nullable: true
          description: >-
            Last date user was sent an onboarding reminder email in ISO 8601
            format, or null if never reminded.

            Full Audit View only - omitted in Controlled Audit View.
          example: '2024-01-15'
        policies:
          allOf:
            - $ref: '#/components/schemas/PeopleSecurityTaskDetails'
          nullable: true
          description: |-
            Policy acceptance task details, or null if not available.
            Full Audit View only - omitted in Controlled Audit View.
        trainings:
          allOf:
            - $ref: '#/components/schemas/PeopleSecurityTaskDetails'
          nullable: true
          description: |-
            Security training task details, or null if not available.
            Full Audit View only - omitted in Controlled Audit View.
        backgroundChecks:
          allOf:
            - $ref: '#/components/schemas/PeopleSecurityTaskDetails'
          nullable: true
          description: |-
            Background check task details, or null if not available.
            Full Audit View only - omitted in Controlled Audit View.
        deviceMonitoring:
          allOf:
            - $ref: '#/components/schemas/PeopleSecurityTaskDetails'
          nullable: true
          description: |-
            Device monitoring task details, or null if not available.
            Full Audit View only - omitted in Controlled Audit View.
        customOnboarding:
          allOf:
            - $ref: '#/components/schemas/PeopleSecurityTaskDetails'
          nullable: true
          description: |-
            Custom onboarding task details, or null if not available.
            Full Audit View only - omitted in Controlled Audit View.
        customOffboarding:
          allOf:
            - $ref: '#/components/schemas/PeopleSecurityTaskDetails'
          nullable: true
          description: |-
            Custom offboarding task details, or null if not available.
            Full Audit View only - omitted in Controlled Audit View.
      required:
        - id
        - name
        - email
      type: object
      additionalProperties: false
    PageInfo:
      description: Provides information about the pagination of a dataset.
      properties:
        endCursor:
          type: string
          nullable: true
          description: >-
            The cursor that points to the end of the current page, or null if
            there is no such cursor.
        hasNextPage:
          type: boolean
          description: Indicates if there is another page after the current page.
        hasPreviousPage:
          type: boolean
          description: Indicates if there is a page before the current page.
        startCursor:
          type: string
          nullable: true
          description: >-
            The cursor that points to the start of the current page, or null if
            there is no such cursor.
      required:
        - endCursor
        - hasNextPage
        - hasPreviousPage
        - startCursor
      type: object
      additionalProperties: false
    PeopleSourceInfo:
      description: |-
        Source information for a person's data.
        Full Audit View only - omitted in Controlled Audit View.
      properties:
        mainSource:
          type: string
          description: Main source of user data.
          example: Okta
        supplementarySource:
          type: string
          nullable: true
          description: Supplementary source, or null if none.
          example: Google Workspace
      required:
        - mainSource
        - supplementarySource
      type: object
      additionalProperties: false
    PeopleTaskStatusInfo:
      description: |-
        Overall task status information for a person.
        Full Audit View only - omitted in Controlled Audit View.
      properties:
        status:
          $ref: '#/components/schemas/PeopleTaskStatus'
          description: Overall task status.
          example: SECURITY_TASKS_COMPLETE
        dueDate:
          type: string
          nullable: true
          description: >-
            Due date for the earliest incomplete task in ISO 8601 format, or
            null if none.
          example: '2024-03-15'
        completionDate:
          type: string
          nullable: true
          description: >-
            Completion date when all tasks are complete in ISO 8601 format, or
            null if incomplete.
          example: '2024-01-20'
        numTasksCompleted:
          type: number
          format: double
          nullable: true
          description: Count of completed tasks, or null if not available.
          example: 5
        numTasksOverdue:
          type: number
          format: double
          nullable: true
          description: Count of overdue tasks, or null if not available.
          example: 2
        numTasksDueSoon:
          type: number
          format: double
          nullable: true
          description: Count of tasks due soon, or null if not available.
          example: 1
      required:
        - status
        - dueDate
        - completionDate
        - numTasksCompleted
        - numTasksOverdue
        - numTasksDueSoon
      type: object
      additionalProperties: false
    PeopleSecurityTaskDetails:
      description: |-
        Security task details for a specific task category.
        Full Audit View only - omitted in Controlled Audit View.
      properties:
        status:
          $ref: '#/components/schemas/PeopleSecurityTaskStatus'
          description: Task status for this category.
          example: SECURITY_TASKS_COMPLETE
        dueDate:
          type: string
          nullable: true
          description: Due date for incomplete task in ISO 8601 format, or null if none.
          example: '2024-03-15'
        completionDate:
          type: string
          nullable: true
          description: >-
            Completion date for completed task in ISO 8601 format, or null if
            incomplete.
          example: '2024-01-20'
      required:
        - status
        - dueDate
        - completionDate
      type: object
      additionalProperties: false
    PeopleTaskStatus:
      type: string
      enum:
        - NO_SECURITY_TASKS
        - OFFBOARDING_COMPLETE
        - OFFBOARDING_DUE_SOON
        - OFFBOARDING_OVERDUE
        - PAUSED
        - SECURITY_TASKS_COMPLETE
        - SECURITY_TASKS_DUE_SOON
        - SECURITY_TASKS_OVERDUE
      description: Overall user task status.
    PeopleSecurityTaskStatus:
      type: string
      enum:
        - NO_SECURITY_TASKS
        - SECURITY_TASKS_COMPLETE
        - SECURITY_TASKS_DUE_SOON
        - SECURITY_TASKS_OVERDUE
      description: Security task status for individual task categories.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````