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

# List candidates in your CRM

> The candidates you own in your Paraform CRM, mainly to find the `candidateId` that other endpoints take. Only your own candidates are ever returned: candidates held by your agency teammates or by an agency owner are never included, even when your agency shares candidates in the app.

Filters are optional and combine with AND. `query` is a free-text search across the candidate's name, headline, location and employer names, so use it for location questions too. `linkedinUrl` and `email` find one specific person: `linkedinUrl` must be the candidate's profile link, `linkedin.com/in/<handle>`, with or without `https://` and `www.`, a trailing slash or a query string, in any casing (other LinkedIn links return 400 `invalid_linkedin_url`), and `email` is an exact, case-insensitive match on an email you can see for the candidate. Neither matching returns an empty list, not an error. `tags` and `relationshipStatus` match ANY of the values given; pass a filter more than once to send several values.

`furthestStatus` is the furthest pipeline status any of the candidate's applications reached (SUBMITTED, INTERVIEWING, OFFER, HIRED and so on), null for a candidate you have never submitted. `relationshipStatus` is your working relationship with them, separate from any application.

Rows come newest first. When `query` is set, candidates whose name matches it come first, then the rest, newest first within each group. A page holds at most 50 candidates. Pass `nextCursor` back as `cursor` for the next page. Hidden and archived candidates are left out.

Required scopes: `candidates:read`.



## OpenAPI

````yaml /api/openapi.json get /recruiter/candidates
openapi: 3.0.0
info:
  title: Paraform API
  version: v1
servers:
  - url: https://external-api.paraform.com/api/external/v1
security: []
paths:
  /recruiter/candidates:
    get:
      summary: List candidates in your CRM
      description: >-
        The candidates you own in your Paraform CRM, mainly to find the
        `candidateId` that other endpoints take. Only your own candidates are
        ever returned: candidates held by your agency teammates or by an agency
        owner are never included, even when your agency shares candidates in the
        app.


        Filters are optional and combine with AND. `query` is a free-text search
        across the candidate's name, headline, location and employer names, so
        use it for location questions too. `linkedinUrl` and `email` find one
        specific person: `linkedinUrl` must be the candidate's profile link,
        `linkedin.com/in/<handle>`, with or without `https://` and `www.`, a
        trailing slash or a query string, in any casing (other LinkedIn links
        return 400 `invalid_linkedin_url`), and `email` is an exact,
        case-insensitive match on an email you can see for the candidate.
        Neither matching returns an empty list, not an error. `tags` and
        `relationshipStatus` match ANY of the values given; pass a filter more
        than once to send several values.


        `furthestStatus` is the furthest pipeline status any of the candidate's
        applications reached (SUBMITTED, INTERVIEWING, OFFER, HIRED and so on),
        null for a candidate you have never submitted. `relationshipStatus` is
        your working relationship with them, separate from any application.


        Rows come newest first. When `query` is set, candidates whose name
        matches it come first, then the rest, newest first within each group. A
        page holds at most 50 candidates. Pass `nextCursor` back as `cursor` for
        the next page. Hidden and archived candidates are left out.


        Required scopes: `candidates:read`.
      operationId: listRecruiterCandidates
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              Free text over name, headline, location and employer names, e.g.
              `Jane Doe` or `Austin`. Name matches first.
          required: false
          description: >-
            Free text over name, headline, location and employer names, e.g.
            `Jane Doe` or `Austin`. Name matches first.
          name: query
          in: query
        - schema:
            type: integer
            nullable: true
            minimum: 0
            default: 0
            description: Previous page's `nextCursor`, same filters. Omit for first page.
          required: false
          description: Previous page's `nextCursor`, same filters. Omit for first page.
          name: cursor
          in: query
        - schema:
            type: integer
            minimum: 1
            default: 10
            description: Candidates per page. Default 10; above 50 lowered to 50.
          required: false
          description: Candidates per page. Default 10; above 50 lowered to 50.
          name: limit
          in: query
        - schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
            description: >-
              CRM tag names, repeat for several, e.g.
              `tags=backend&tags=senior`. Matches ANY.
          required: false
          description: >-
            CRM tag names, repeat for several, e.g. `tags=backend&tags=senior`.
            Matches ANY.
          name: tags
          in: query
        - schema:
            anyOf:
              - type: string
                enum:
                  - SOURCED
                  - CONTACTED
                  - REPLIED
                  - SCHEDULED_CALL
                  - SCREENED
                  - ACTIVE
                  - STAY_IN_TOUCH
                  - BACKBURNER
              - type: array
                items:
                  type: string
                  enum:
                    - SOURCED
                    - CONTACTED
                    - REPLIED
                    - SCHEDULED_CALL
                    - SCREENED
                    - ACTIVE
                    - STAY_IN_TOUCH
                    - BACKBURNER
              - nullable: true
            description: >-
              Your working relationship with candidate, repeat for several;
              matches ANY. Unknown value ignored.
          required: false
          description: >-
            Your working relationship with candidate, repeat for several;
            matches ANY. Unknown value ignored.
          name: relationshipStatus
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              Candidate LinkedIn profile link, e.g.
              `https://www.linkedin.com/in/janedoe`. Other LinkedIn link returns
              400 `invalid_linkedin_url`. No match returns empty list.
          required: false
          description: >-
            Candidate LinkedIn profile link, e.g.
            `https://www.linkedin.com/in/janedoe`. Other LinkedIn link returns
            400 `invalid_linkedin_url`. No match returns empty list.
          name: linkedinUrl
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              Email you can see for candidate, exact, case-insensitive, e.g.
              `jane@example.com`. No match returns empty list.
          required: false
          description: >-
            Email you can see for candidate, exact, case-insensitive, e.g.
            `jane@example.com`. No match returns empty list.
          name: email
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  candidates:
                    type: array
                    items:
                      type: object
                      properties:
                        candidateId:
                          type: string
                        name:
                          type: string
                          nullable: true
                        linkedinUrl:
                          type: string
                          nullable: true
                        location:
                          type: string
                          nullable: true
                        oneLiner:
                          type: string
                          nullable: true
                        currentRole:
                          type: object
                          nullable: true
                          properties:
                            company:
                              type: string
                            title:
                              type: string
                          required:
                            - company
                            - title
                        relationshipStatus:
                          type: string
                        furthestStatus:
                          type: string
                          nullable: true
                        tags:
                          type: array
                          items:
                            type: string
                        addedAt:
                          type: string
                      required:
                        - candidateId
                        - name
                        - linkedinUrl
                        - location
                        - oneLiner
                        - currentRole
                        - relationshipStatus
                        - furthestStatus
                        - tags
                        - addedAt
                  nextCursor:
                    type: number
                required:
                  - candidates
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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