> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revcenter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List the candidate database

> Everyone any of this workspace's searches found, newest first, as the Candidates tab lists them; filter by text, project, title, company or place. Does not use shortlist credits.

Needs scope `shortlists:read`.



## OpenAPI

````yaml /openapi.json get /candidates
openapi: 3.1.0
info:
  title: Revcenter API
  version: v1
  description: >-
    Projects, searches, scored candidates and shortlists. Generated from the
    agent API's registry.
servers:
  - url: https://api.revcenter.ai/v1
security:
  - bearer: []
tags:
  - name: Login
  - name: Account
  - name: Actions
  - name: Reference
  - name: Projects
  - name: Searches
  - name: Scoring
  - name: Shortlists
  - name: Candidates
  - name: Health
paths:
  /candidates:
    get:
      tags:
        - Candidates
      summary: List the candidate database
      description: >-
        Everyone any of this workspace's searches found, newest first, as the
        Candidates tab lists them; filter by text, project, title, company or
        place. Does not use shortlist credits.


        Needs scope `shortlists:read`.
      operationId: list_candidates
      parameters:
        - name: q
          in: query
          required: false
          description: Name, title, company or headline contains this
          schema:
            type: string
        - name: project_id
          in: query
          required: false
          description: Only people a search in this project found
          schema:
            type: string
        - name: title
          in: query
          required: false
          description: Current title contains this
          schema:
            type: string
        - name: company
          in: query
          required: false
          description: Current company contains this
          schema:
            type: string
        - name: location
          in: query
          required: false
          description: Location contains this
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Up to 500 per page (default 100; 50 for projects).
          schema:
            type: integer
        - name: cursor
          in: query
          required: false
          description: The `cursor` from the previous page. Omit for the first page.
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              description: >-
                Requests allowed this minute (the tighter of the key's and the
                workspace's).
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests left this minute.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: When the minute resets, in Unix seconds.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Candidate'
                  cursor:
                    type:
                      - string
                      - 'null'
                    description: Pass as ?cursor= for the next page; null on the last.
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  - id: 5b1e7c2a-9d3f-4a6b-8c1e-2f4a6b8c1e3d
                    name: Dana Whitfield
                    title: Plant Controller
                    company: Garden State Foods
                    location: Cherry Hill, NJ
                    headline: Plant Controller at Garden State Foods
                    linkedin_url: https://www.linkedin.com/in/example
                    experience_years: 14
                    open_to_work: false
                    school: Rutgers University
                    projects:
                      - id: 6f1c2a0e-3b7d-4c1e-9a52-0d4e8b7c1a11
                        name: Plant Controller, Camden NJ
                    last_found_at: '2026-10-01T14:02:11.000Z'
                cursor: null
                meta:
                  request_id: req_01JABCDEF
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
components:
  schemas:
    Candidate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        title:
          type:
            - string
            - 'null'
        company:
          type:
            - string
            - 'null'
        location:
          type:
            - string
            - 'null'
        headline:
          type:
            - string
            - 'null'
        linkedin_url:
          type:
            - string
            - 'null'
        experience_years:
          type:
            - number
            - 'null'
        open_to_work:
          type: boolean
        school:
          type:
            - string
            - 'null'
        projects:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type:
                  - string
                  - 'null'
        last_found_at:
          type: string
    Meta:
      type: object
      properties:
        request_id:
          type: string
        total:
          type: integer
          description: On lists that count everything that matched.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: 'Stable: every code is on the Errors page.'
            message:
              type: string
            details:
              type:
                - object
                - 'null'
              description: >-
                Structured specifics, when there are any (for example
                retry_after_seconds).
            request_id:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'
      example:
        error:
          code: search_not_found
          message: No search with that id in this workspace.
          details: null
          request_id: req_01JABCDEF
        meta:
          request_id: req_01JABCDEF
  responses:
    Error:
      description: 'An error: one envelope everywhere. A 429 carries Retry-After.'
      headers:
        X-RateLimit-Limit:
          description: >-
            Requests allowed this minute (the tighter of the key's and the
            workspace's).
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left this minute.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: When the minute resets, in Unix seconds.
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait (on 429 and 503).
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An API key from Settings → Usage → API (rvc_live_…).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.