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

# Get Candidates

> Retrieve all candidates for the authenticated organization. Results are paginated (default 100 per page, max 1000); use the page and pageSize query parameters to page through the full set, and read the returned pagination.totalPages to know when to stop. Optionally filter by integration source and external ID.



## OpenAPI

````yaml https://api.ropes.ai/api/docs/openapi.json get /api/public/candidates
openapi: 3.0.0
info:
  title: Ropes Public API
  version: 1.0.0
  description: >-
    Public API for Ropes. Authenticate using your API key in the x-api-key
    header.
servers:
  - url: https://api.ropes.ai
    description: Production server
  - url: http://localhost:3001
    description: Local development server
security: []
paths:
  /api/public/candidates:
    get:
      tags:
        - Candidates
      summary: Get Candidates
      description: >-
        Retrieve all candidates for the authenticated organization. Results are
        paginated (default 100 per page, max 1000); use the page and pageSize
        query parameters to page through the full set, and read the returned
        pagination.totalPages to know when to stop. Optionally filter by
        integration source and external ID.
      parameters:
        - schema:
            type: string
            description: Filter by integration source. Must be provided with externalId.
          required: false
          description: Filter by integration source. Must be provided with externalId.
          name: integrationSource
          in: query
        - schema:
            type: string
            description: >-
              Filter by external ID from the ATS integration. Must be provided
              with integrationSource.
          required: false
          description: >-
            Filter by external ID from the ATS integration. Must be provided
            with integrationSource.
          name: externalId
          in: query
        - schema:
            type: integer
            minimum: 1
            default: 1
            description: 'Page number (default: 1)'
          required: false
          description: 'Page number (default: 1)'
          name: page
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
            description: 'Number of candidates per page (default: 100, max: 1000)'
          required: false
          description: 'Number of candidates per page (default: 100, max: 1000)'
          name: pageSize
          in: query
      responses:
        '200':
          description: Successfully retrieved candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidatesResponse'
        '400':
          description: >-
            Bad request - integrationSource and externalId must be provided
            together
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CandidatesResponse:
      type: object
      properties:
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/Candidate'
          description: List of candidates for the current page
        pagination:
          $ref: '#/components/schemas/CandidatesPagination'
      required:
        - candidates
        - pagination
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        message:
          type: string
          description: Error message (alternative field)
    Candidate:
      type: object
      properties:
        name:
          type: string
          description: The full name of the candidate
        email:
          type: string
          format: email
          description: The email address of the candidate
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the candidate was created
        identifier:
          type: string
          description: Unique identifier for the candidate
        status:
          type: string
          enum:
            - Not Assigned
            - Assigned
            - Expired
            - Completed
            - Passed
            - Failed
            - Error
          description: Current status of the candidate
        integrationSource:
          type: string
          description: Integration source that created this candidate
        externalId:
          type: string
          description: External ID from the integration source (e.g., ATS candidate ID)
      required:
        - name
        - email
        - createdAt
        - identifier
        - status
    CandidatesPagination:
      type: object
      properties:
        page:
          type: number
          description: Current page number
        pageSize:
          type: number
          description: Number of candidates per page
        totalItems:
          type: number
          description: Total number of candidates matching the query
        totalPages:
          type: number
          description: Total number of pages
      required:
        - page
        - pageSize
        - totalItems
        - totalPages
      description: Pagination metadata
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````