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

# ParaAI matches sent to you by hiring managers

> ParaAI matches sent to you: a hiring manager looked at a candidate profile, asked for that specific candidate on a specific role, and Paraform routed the request to you because the candidate is in your CRM. This is a different list from `listRecommendedRolesForCandidate`, where Paraform's model suggests roles; here a person asked.

Each row carries the hiring manager's name and their note on why they want the candidate, the role with its pay and your fee, the candidate, and the deadline. A pending match expires 7 days after it is sent (`daysUntilExpiry`), and unresolved expired matches can pause ParaAI matching for you, so the oldest pending rows are the most urgent.

`actionBucket` says what to do: `new` means nobody has contacted the candidate, `needs_submission` means you marked them contacted but have not submitted, `expired` means the window closed, `closed` means submitted or passed.

`status` narrows the list: `pending` (default), `expired`, `dismissed`, `submitted`, or `all`. Pending matches on closed roles are left out; resolved matches are kept. Rows come back oldest first. A page holds at most 20 matches. Pass `nextCursor` back as `cursor`, with the same `status`, for the next page; `nextCursor` is absent on the last page. The cursor marks a position, so acting on a match between pages does not skip or repeat rows.

`role.feePercent` is null when your agency hides payment from its members; agency owners always see it. `role.urls.recruit` is null until you are approved on the role.

When `role.company.confidentialSearch` is true the search is confidential: candidate-facing copy must refer to the employer as `role.company.anonymizedName` and must not name the company or quote copy that identifies it.

This endpoint is read-only; contacting, passing and submitting happen in the Paraform app.

Required scopes: `candidates:read`, `roles:read`, `submissions:read`.



## OpenAPI

````yaml /api/openapi.json get /recruiter/paraai-recommendations
openapi: 3.0.0
info:
  title: Paraform API
  version: v1
servers:
  - url: https://external-api.paraform.com/api/external/v1
security: []
paths:
  /recruiter/paraai-recommendations:
    get:
      summary: ParaAI matches sent to you by hiring managers
      description: >-
        ParaAI matches sent to you: a hiring manager looked at a candidate
        profile, asked for that specific candidate on a specific role, and
        Paraform routed the request to you because the candidate is in your CRM.
        This is a different list from `listRecommendedRolesForCandidate`, where
        Paraform's model suggests roles; here a person asked.


        Each row carries the hiring manager's name and their note on why they
        want the candidate, the role with its pay and your fee, the candidate,
        and the deadline. A pending match expires 7 days after it is sent
        (`daysUntilExpiry`), and unresolved expired matches can pause ParaAI
        matching for you, so the oldest pending rows are the most urgent.


        `actionBucket` says what to do: `new` means nobody has contacted the
        candidate, `needs_submission` means you marked them contacted but have
        not submitted, `expired` means the window closed, `closed` means
        submitted or passed.


        `status` narrows the list: `pending` (default), `expired`, `dismissed`,
        `submitted`, or `all`. Pending matches on closed roles are left out;
        resolved matches are kept. Rows come back oldest first. A page holds at
        most 20 matches. Pass `nextCursor` back as `cursor`, with the same
        `status`, for the next page; `nextCursor` is absent on the last page.
        The cursor marks a position, so acting on a match between pages does not
        skip or repeat rows.


        `role.feePercent` is null when your agency hides payment from its
        members; agency owners always see it. `role.urls.recruit` is null until
        you are approved on the role.


        When `role.company.confidentialSearch` is true the search is
        confidential: candidate-facing copy must refer to the employer as
        `role.company.anonymizedName` and must not name the company or quote
        copy that identifies it.


        This endpoint is read-only; contacting, passing and submitting happen in
        the Paraform app.


        Required scopes: `candidates:read`, `roles:read`, `submissions:read`.
      operationId: listParaAIRecommendations
      parameters:
        - schema:
            type: string
            nullable: true
            enum:
              - pending
              - expired
              - dismissed
              - submitted
              - all
            default: pending
            description: >-
              Which matches: pending (default), expired, dismissed, submitted,
              or all. Unknown value falls back to pending.
          required: false
          description: >-
            Which matches: pending (default), expired, dismissed, submitted, or
            all. Unknown value falls back to pending.
          name: status
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 2048
            description: >-
              Previous page's `nextCursor`, verbatim, same `status`. Omit for
              first page.
          required: false
          description: >-
            Previous page's `nextCursor`, verbatim, same `status`. Omit for
            first page.
          name: cursor
          in: query
        - schema:
            type: integer
            minimum: 1
            default: 10
            description: Matches per page. Default 10; above 20 lowered to 20.
          required: false
          description: Matches per page. Default 10; above 20 lowered to 20.
          name: limit
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  recommendations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                          description: pending, submitted, dismissed or expired.
                        actionBucket:
                          type: string
                          enum:
                            - new
                            - needs_submission
                            - expired
                            - closed
                          description: >-
                            Next step: new, needs_submission, expired or closed.
                            See endpoint description.
                        sentAt:
                          type: string
                          description: When hiring manager sent match, ISO 8601.
                        daysUntilExpiry:
                          type: number
                          nullable: true
                          description: >-
                            Whole days until pending match expires, 0 on last
                            day; null once resolved.
                        reachedOutToCandidate:
                          type: boolean
                          description: You marked candidate contacted.
                        hiringManagerNote:
                          type: string
                          nullable: true
                          description: >-
                            Hiring manager's own words on why they want
                            candidate.
                        hiringManagerName:
                          type: string
                          description: Hiring manager who sent match.
                        candidate:
                          type: object
                          properties:
                            candidateId:
                              type: string
                              description: >-
                                Pass to getRecruiterCandidate for full profile;
                                404 if candidate since left your CRM.
                            name:
                              type: string
                            title:
                              type: string
                              nullable: true
                            oneLiner:
                              type: string
                              nullable: true
                            location:
                              type: string
                              nullable: true
                            linkedinUrl:
                              type: string
                              nullable: true
                          required:
                            - candidateId
                            - name
                            - title
                            - oneLiner
                            - location
                            - linkedinUrl
                        role:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            urls:
                              type: object
                              properties:
                                browse:
                                  type: string
                                recruit:
                                  type: string
                                  nullable: true
                              required:
                                - browse
                                - recruit
                              description: >-
                                browse: role page. recruit: your workspace on
                                role, null until approved.
                            locations:
                              type: array
                              items:
                                type: string
                            company:
                              type: object
                              properties:
                                name:
                                  type: string
                                confidentialSearch:
                                  type: boolean
                                  description: >-
                                    True for confidential search:
                                    candidate-facing copy uses `anonymizedName`,
                                    never `name`.
                                anonymizedName:
                                  type: string
                                  nullable: true
                                  description: >-
                                    Employer name for candidate-facing copy;
                                    null unless confidential.
                              required:
                                - name
                                - confidentialSearch
                                - anonymizedName
                            compensation:
                              type: object
                              properties:
                                salaryLowerBound:
                                  type: number
                                  nullable: true
                                salaryUpperBound:
                                  type: number
                                  nullable: true
                                currency:
                                  type: string
                                  nullable: true
                              required:
                                - salaryLowerBound
                                - salaryUpperBound
                                - currency
                            feePercent:
                              type: number
                              nullable: true
                              description: >-
                                Your placement fee, percent of first-year
                                salary; null when agency hides payment.
                          required:
                            - id
                            - name
                            - urls
                            - locations
                            - company
                            - compensation
                            - feePercent
                        application:
                          type: object
                          properties:
                            progressLabel:
                              type: string
                              nullable: true
                              description: >-
                                Submission stage: Submitted, First round, Mid
                                round, Final round, Offer, Hired or Rejected.
                                Null until submitted.
                            rejectedAfterStage:
                              type: string
                              nullable: true
                              description: >-
                                Rejected submission's furthest stage, as
                                progressLabel value. Null unless rejected.
                          required:
                            - progressLabel
                            - rejectedAfterStage
                          description: Submission progress, once submitted.
                      required:
                        - id
                        - status
                        - actionBucket
                        - sentAt
                        - daysUntilExpiry
                        - reachedOutToCandidate
                        - hiringManagerNote
                        - hiringManagerName
                        - candidate
                        - role
                        - application
                  nextCursor:
                    type: string
                    description: >-
                      Absent on last page. Opaque: send back verbatim as
                      `cursor`.
                required:
                  - recommendations
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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