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

# Your recommended submissions, across every candidate in your CRM

> The "Recommended submissions" list from your Paraform home page: for every candidate in your CRM, the roles Paraform's matching model recommends you submit them to. Candidates come in order of their strongest pair, and each candidate's roles come strongest first. Recruiters also call these "single sub recs", because most are roles where you would submit without holding a primary slot.

Use this for questions across the whole CRM, such as "review my single sub recs and tell me which to act on". For one named candidate use `listRecommendedRolesForCandidate` instead. Never answer the whole-CRM question by looping that endpoint over every candidate: this call returns the same rows at once.

Pairs are ranked ENDORSED before SUGGESTED and by match strength inside each band. The list already leaves out candidates hired recently, roles the candidate was already submitted to, and roles you cannot submit to. Every role carries the full `listRecruiterRoles` shape, so you can rank by payout, competition and whether you hold the slot.

This read returns at most 20 (candidate, role) pairs, the strongest first. An empty list with `enabled` true means Paraform has no active recommendation for any of your candidates right now.

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



## OpenAPI

````yaml /api/openapi.json get /recruiter/recommendations
openapi: 3.0.0
info:
  title: Paraform API
  version: v1
servers:
  - url: https://external-api.paraform.com/api/external/v1
security: []
paths:
  /recruiter/recommendations:
    get:
      summary: Your recommended submissions, across every candidate in your CRM
      description: >-
        The "Recommended submissions" list from your Paraform home page: for
        every candidate in your CRM, the roles Paraform's matching model
        recommends you submit them to. Candidates come in order of their
        strongest pair, and each candidate's roles come strongest first.
        Recruiters also call these "single sub recs", because most are roles
        where you would submit without holding a primary slot.


        Use this for questions across the whole CRM, such as "review my single
        sub recs and tell me which to act on". For one named candidate use
        `listRecommendedRolesForCandidate` instead. Never answer the whole-CRM
        question by looping that endpoint over every candidate: this call
        returns the same rows at once.


        Pairs are ranked ENDORSED before SUGGESTED and by match strength inside
        each band. The list already leaves out candidates hired recently, roles
        the candidate was already submitted to, and roles you cannot submit to.
        Every role carries the full `listRecruiterRoles` shape, so you can rank
        by payout, competition and whether you hold the slot.


        This read returns at most 20 (candidate, role) pairs, the strongest
        first. An empty list with `enabled` true means Paraform has no active
        recommendation for any of your candidates right now.


        Required scopes: `candidates:read`, `roles:read`.
      operationId: listRecruiterRecommendations
      parameters:
        - schema:
            type: integer
            minimum: 1
            default: 10
            description: Pairs per page. Default 10; above 20 lowered to 20.
          required: false
          description: Pairs per page. Default 10; above 20 lowered to 20.
          name: limit
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                  candidates:
                    type: array
                    items:
                      type: object
                      properties:
                        candidateId:
                          type: string
                        name:
                          type: string
                        title:
                          type: string
                          nullable: true
                        linkedinUrl:
                          type: string
                          nullable: true
                        roles:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              postedAt:
                                type: string
                                nullable: true
                              urls:
                                type: object
                                properties:
                                  browse:
                                    type: string
                                  recruit:
                                    type: string
                                    nullable: true
                                required:
                                  - browse
                                  - recruit
                              company:
                                type: object
                                properties:
                                  name:
                                    type: string
                                  confidentialSearch:
                                    type: boolean
                                  anonymizedName:
                                    type: string
                                    nullable: true
                                  oneLiner:
                                    type: string
                                    nullable: true
                                  industries:
                                    type: array
                                    items:
                                      type: string
                                  size:
                                    type: number
                                    nullable: true
                                required:
                                  - name
                                  - confidentialSearch
                                  - anonymizedName
                                  - oneLiner
                                  - industries
                                  - size
                              locations:
                                type: array
                                items:
                                  type: string
                              workplaceType:
                                type: string
                                nullable: true
                              roleTypes:
                                type: array
                                items:
                                  type: string
                              techStack:
                                type: array
                                items:
                                  type: string
                              visaText:
                                type: string
                                nullable: true
                              compensation:
                                type: object
                                properties:
                                  salaryLowerBound:
                                    type: number
                                  salaryUpperBound:
                                    type: number
                                  currency:
                                    type: string
                                    nullable: true
                                  equity:
                                    type: string
                                    nullable: true
                                required:
                                  - salaryLowerBound
                                  - salaryUpperBound
                                  - currency
                                  - equity
                              experience:
                                type: object
                                properties:
                                  yearsMin:
                                    type: number
                                  yearsMax:
                                    type: number
                                    nullable: true
                                required:
                                  - yearsMin
                                  - yearsMax
                              fee:
                                type: object
                                properties:
                                  amountLowerBound:
                                    type: number
                                    nullable: true
                                  percentOfSalary:
                                    type: number
                                    nullable: true
                                  boostPercent:
                                    type: number
                                    nullable: true
                                  bonusAmount:
                                    type: number
                                    nullable: true
                                  firstSubmissionReward:
                                    type: number
                                    nullable: true
                                required:
                                  - amountLowerBound
                                  - percentOfSalary
                                  - boostPercent
                                  - bonusAmount
                                  - firstSubmissionReward
                              pipeline:
                                type: object
                                properties:
                                  totalApplications:
                                    type: number
                                    nullable: true
                                  totalInterviewing:
                                    type: number
                                  totalHired:
                                    type: number
                                  openingsText:
                                    type: string
                                required:
                                  - totalApplications
                                  - totalInterviewing
                                  - totalHired
                                  - openingsText
                              myRole:
                                type: object
                                properties:
                                  isApproved:
                                    type: boolean
                                  isPrimary:
                                    type: boolean
                                  accessLevel:
                                    type: string
                                    nullable: true
                                  approvalStatus:
                                    type: string
                                    nullable: true
                                  submissions:
                                    type: object
                                    properties:
                                      submitted:
                                        type: number
                                      interviewing:
                                        type: number
                                      hired:
                                        type: number
                                      total:
                                        type: number
                                    required:
                                      - submitted
                                      - interviewing
                                      - hired
                                      - total
                                  trial:
                                    type: object
                                    nullable: true
                                    properties:
                                      endsAt:
                                        type: string
                                        nullable: true
                                      businessDaysLeft:
                                        type: number
                                        nullable: true
                                      submissionGoal:
                                        type: number
                                      submissionsCounted:
                                        type: number
                                      isActive:
                                        type: boolean
                                      endingSoon:
                                        type: boolean
                                    required:
                                      - endsAt
                                      - businessDaysLeft
                                      - submissionGoal
                                      - submissionsCounted
                                      - isActive
                                      - endingSoon
                                required:
                                  - isApproved
                                  - isPrimary
                                  - accessLevel
                                  - approvalStatus
                                  - submissions
                                  - trial
                              recruiterAccess:
                                type: object
                                properties:
                                  atMaxCapacity:
                                    type: boolean
                                  notAcceptingRecruiters:
                                    type: boolean
                                  density:
                                    type: string
                                    nullable: true
                                required:
                                  - atMaxCapacity
                                  - notAcceptingRecruiters
                                  - density
                              hiringManager:
                                type: object
                                properties:
                                  lastActiveAt:
                                    type: string
                                    nullable: true
                                  responsivenessDays:
                                    type: number
                                  engagement:
                                    type: object
                                    nullable: true
                                    properties:
                                      finalRating:
                                        type: number
                                        nullable: true
                                      percentileRank:
                                        type: number
                                        nullable: true
                                    required:
                                      - finalRating
                                      - percentileRank
                                required:
                                  - lastActiveAt
                                  - responsivenessDays
                                  - engagement
                              recommendation:
                                type: object
                                properties:
                                  band:
                                    type: string
                                required:
                                  - band
                            required:
                              - id
                              - name
                              - postedAt
                              - urls
                              - company
                              - locations
                              - workplaceType
                              - roleTypes
                              - techStack
                              - visaText
                              - compensation
                              - experience
                              - fee
                              - pipeline
                              - myRole
                              - recruiterAccess
                              - hiringManager
                              - recommendation
                      required:
                        - candidateId
                        - name
                        - title
                        - linkedinUrl
                        - roles
                required:
                  - enabled
                  - 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.