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

# Roles recommended for one of your candidates

> Paraform's own matching for a specific candidate: the roles it recommends you submit them to, strongest first, each with the reasoning behind it.

This is the tool for "which roles suit this person" when the recruiter has a candidate in mind. Matching reads the candidate's full profile. `listRecruiterRoles` is for finding roles to work on when no particular candidate is in play.

`candidateId` is the `candidateId` field from `listRecruiterCandidates`. The candidate must be in your own CRM: any other id, including a teammate's, answers 404.

`status` is `ready` or `generating`. `generating` means Paraform is building this candidate's recommendations now: `roles` is empty, and you should repeat the same request after `retryAfterSeconds` (about 15 to 30 seconds). Repeating it is safe. `ready` with an empty `roles` array means generation finished and no available recommendations could be found for the candidate. That does not mean no role could ever fit: `listRecruiterRoles` with filters drawn from what is known about the candidate is the fallback. Stored recommendations are served as they are and refreshed in the background once they are about a week old. A null `status` means Paraform cannot recommend roles for this candidate right now: `roles` is empty and `message` says why (a missing resume or job preferences, an unreadable resume, a candidate Paraform does not recommend for, or generation failing repeatedly in the last day), naming what to fix on the Candidates page when the recruiter can. Repeating the request soon does not change it.

`recommendation.band` is `ENDORSED` (a strong match) or `SUGGESTED` (worth a look). Every role carries the same fields `listRecruiterRoles` returns, including `myRole` and `fee`, and only roles you could see and submit this candidate to are listed. `fee` amounts are `null` field by field for members of an agency whose owner hides payment details; `null` means hidden, not zero. The list is short by design, at most 20 roles.

`recommendation.fit` is the reasoning: the verdict (`rating` and its `label`), a `summary` paragraph, and per-requirement assessments with their reasoning and evidence from the candidate's profile. `complete` is false while parts of the analysis are still being written, and `fit` is `null` when no saved analysis exists yet; the role is still a valid recommendation and a later request can fill it in.

404, carrying `details.candidatesUrl` (the Candidates page), means the candidate is not in your CRM.

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



## OpenAPI

````yaml /api/openapi.json get /recruiter/candidates/{candidateId}/recommended-roles
openapi: 3.0.0
info:
  title: Paraform API
  version: v1
servers:
  - url: https://external-api.paraform.com/api/external/v1
security: []
paths:
  /recruiter/candidates/{candidateId}/recommended-roles:
    get:
      summary: Roles recommended for one of your candidates
      description: >-
        Paraform's own matching for a specific candidate: the roles it
        recommends you submit them to, strongest first, each with the reasoning
        behind it.


        This is the tool for "which roles suit this person" when the recruiter
        has a candidate in mind. Matching reads the candidate's full profile.
        `listRecruiterRoles` is for finding roles to work on when no particular
        candidate is in play.


        `candidateId` is the `candidateId` field from `listRecruiterCandidates`.
        The candidate must be in your own CRM: any other id, including a
        teammate's, answers 404.


        `status` is `ready` or `generating`. `generating` means Paraform is
        building this candidate's recommendations now: `roles` is empty, and you
        should repeat the same request after `retryAfterSeconds` (about 15 to 30
        seconds). Repeating it is safe. `ready` with an empty `roles` array
        means generation finished and no available recommendations could be
        found for the candidate. That does not mean no role could ever fit:
        `listRecruiterRoles` with filters drawn from what is known about the
        candidate is the fallback. Stored recommendations are served as they are
        and refreshed in the background once they are about a week old. A null
        `status` means Paraform cannot recommend roles for this candidate right
        now: `roles` is empty and `message` says why (a missing resume or job
        preferences, an unreadable resume, a candidate Paraform does not
        recommend for, or generation failing repeatedly in the last day), naming
        what to fix on the Candidates page when the recruiter can. Repeating the
        request soon does not change it.


        `recommendation.band` is `ENDORSED` (a strong match) or `SUGGESTED`
        (worth a look). Every role carries the same fields `listRecruiterRoles`
        returns, including `myRole` and `fee`, and only roles you could see and
        submit this candidate to are listed. `fee` amounts are `null` field by
        field for members of an agency whose owner hides payment details; `null`
        means hidden, not zero. The list is short by design, at most 20 roles.


        `recommendation.fit` is the reasoning: the verdict (`rating` and its
        `label`), a `summary` paragraph, and per-requirement assessments with
        their reasoning and evidence from the candidate's profile. `complete` is
        false while parts of the analysis are still being written, and `fit` is
        `null` when no saved analysis exists yet; the role is still a valid
        recommendation and a later request can fill it in.


        404, carrying `details.candidatesUrl` (the Candidates page), means the
        candidate is not in your CRM.


        Required scopes: `candidates:read`, `roles:read`.
      operationId: listRecommendedRolesForCandidate
      parameters:
        - schema:
            type: string
            minLength: 1
          required: true
          name: candidateId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  candidateId:
                    type: string
                  status:
                    type: string
                    nullable: true
                    enum:
                      - ready
                      - generating
                  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
                            fit:
                              type: object
                              nullable: true
                              properties:
                                rating:
                                  type: string
                                  enum:
                                    - GOOD_FIT
                                    - MAYBE
                                    - BAD_FIT
                                label:
                                  type: string
                                summary:
                                  type: string
                                  nullable: true
                                complete:
                                  type: boolean
                                requirements:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      description:
                                        type: string
                                      importance:
                                        type: string
                                        enum:
                                          - DEALBREAKER
                                          - REQUIRED
                                          - YEARS_OF_EXPERIENCE
                                          - OPTIONAL
                                      assessment:
                                        type: string
                                        enum:
                                          - GOOD_FIT
                                          - MAYBE
                                          - BAD_FIT
                                          - UNKNOWN
                                      reasoning:
                                        type: string
                                        nullable: true
                                      candidateEvidence:
                                        type: array
                                        items:
                                          type: string
                                    required:
                                      - description
                                      - importance
                                      - assessment
                                      - reasoning
                                      - candidateEvidence
                              required:
                                - rating
                                - label
                                - summary
                                - complete
                                - requirements
                          required:
                            - band
                            - fit
                      required:
                        - id
                        - name
                        - postedAt
                        - urls
                        - company
                        - locations
                        - workplaceType
                        - roleTypes
                        - techStack
                        - visaText
                        - compensation
                        - experience
                        - fee
                        - pipeline
                        - myRole
                        - recruiterAccess
                        - hiringManager
                        - recommendation
                  message:
                    type: string
                  retryAfterSeconds:
                    type: number
                required:
                  - candidateId
                  - status
                  - roles
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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