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

# Get candidates

> Get a paginated list of candidates



## OpenAPI

````yaml get /v1.0/{company_id}/candidates
openapi: 3.0.0
info:
  title: HireHive API reference
  termsOfService: https://www.hirehive.com/terms/
  contact:
    email: support@hirehive.com
  version: v1.0
servers:
  - url: https://api.hirehive.com
security:
  - bearerAuth: []
paths:
  /v1.0/{company_id}/candidates:
    get:
      tags:
        - Candidates
      operationId: Candidates_GetCandidates
      parameters:
        - name: company_id
          in: path
          required: true
          schema:
            type: string
            format: string
          x-position: 1
        - name: sort
          in: query
          description: 'Sortable fields: `first_name`, `last_name`.'
          schema:
            type: string
          x-position: 2
        - name: email
          in: query
          description: Filter candidates by email address
          schema:
            type: string
          x-position: 3
        - name: first_name
          in: query
          description: Filter candidates by first name
          schema:
            type: string
          x-position: 4
        - name: last_name
          in: query
          description: Filter candidates by last name
          schema:
            type: string
          x-position: 5
        - name: rating
          in: query
          description: Filter candidates by star rating
          schema:
            type: integer
            format: int32
            nullable: true
          x-position: 6
        - name: tags
          in: query
          style: form
          explode: true
          description: 'A list of tags to filter by: eg tag_kiZyCd'
          schema:
            type: string
            format: string
            items:
              type: integer
              format: int32
          x-position: 7
        - name: page
          in: query
          description: Defaults to 1
          schema:
            type: integer
            format: int32
          x-position: 8
        - name: page_size
          in: query
          description: Defaults to 30. Min = 1. Max = 100
          schema:
            type: integer
            format: int32
            maximum: 100
            minimum: 1
          x-position: 9
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResponseOfCandidateDto'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
components:
  schemas:
    PagedResponseOfCandidateDto:
      type: object
      additionalProperties: false
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        links:
          $ref: '#/components/schemas/Links'
        items:
          type: array
          items:
            $ref: '#/components/schemas/CandidateDto'
    ValidationProblemDetails:
      type: object
      additionalProperties:
        nullable: true
      properties:
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
    Meta:
      type: object
      additionalProperties: false
      properties:
        page_size:
          type: integer
          format: int32
        page:
          type: integer
          format: int32
        total_items:
          type: integer
          format: int32
        total_pages:
          type: integer
          format: int32
        has_next_page:
          type: boolean
        has_previous_page:
          type: boolean
    Links:
      type: object
      additionalProperties: false
      properties:
        first:
          type: string
        last:
          type: string
        next:
          type: string
        previous:
          type: string
    CandidateDto:
      type: object
      additionalProperties: false
      required:
        - first_name
        - last_name
        - tags
      properties:
        id:
          type: string
          description: The id of the candidate, format `can_abc123`.
          format: int32
        full_name:
          type: string
          description: The full name of the candidate.
        first_name:
          type: string
          description: The first name of the candidate.
          minLength: 1
        last_name:
          type: string
          description: The last name of the candidate.
          minLength: 1
        email:
          type: string
          description: The email address of the candidate.
        phone_number:
          type: string
          description: The phone number of the candidate.
        title:
          type: string
          description: The current job title of the candidate.
        company:
          type: string
          description: The current company of the candidate.
        location:
          $ref: '#/components/schemas/LocationInfoDto'
        image_url:
          type: string
          description: An image url to a profile picture
        tags:
          type: array
          description: A list of tags applied to the candidate.
          items:
            $ref: '#/components/schemas/CandidateTag'
        rating:
          type: integer
          description: A 1-5 star rating assigned to the candidate.
          format: int32
          nullable: true
        application_ids:
          type: array
          description: >-
            A list of other application ids this candidate may have. Format
            `app_abc123`.
          items:
            type: string
            format: int32
        social_profiles:
          type: array
          items:
            $ref: '#/components/schemas/PortfolioLink'
    LocationInfoDto:
      type: object
      additionalProperties: false
      properties:
        address:
          type: string
          description: The city/street address of the candidate.
        country:
          $ref: '#/components/schemas/CountryInfoDto'
    CandidateTag:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: int32
        name:
          type: string
    PortfolioLink:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/LinkTypesEnum'
        uri:
          type: string
    CountryInfoDto:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: The country name of the candidate.
        code:
          type: string
          description: >-
            The 2 letter ISO country code of the candidate. eg US, FR, ES, IT,
            IE
    LinkTypesEnum:
      type: string
      description: ''
      x-enumNames:
        - LinkedIn
        - Twitter
        - Facebook
        - Github
        - GithubUsername
        - Gitlab
        - Codepen
        - Dribble
        - Instagram
        - Other
        - Stackoverflow
        - PersonalSite
        - Behance
      enum:
        - linked_in
        - twitter
        - facebook
        - github
        - github_username
        - gitlab
        - codepen
        - dribble
        - instagram
        - other
        - stackoverflow
        - personal_site
        - behance
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````