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

# Everything you can see about one role

> Use before drafting about role. roleId from listRecruiterRoles. When pitch.outreachTemplates not empty, base outreach on them; keep their wording and facts. When company.confidentialSearch true, candidate-facing copy names employer only as company.anonymizedName. pipeline.mySubmissions and summary.myRole.submissions are not agency totals.

Required scopes: `roles:read`.



## OpenAPI

````yaml /api/openapi.json get /recruiter/roles/{roleId}
openapi: 3.0.0
info:
  title: Paraform API
  version: v1
servers:
  - url: https://external-api.paraform.com/api/external/v1
security: []
paths:
  /recruiter/roles/{roleId}:
    get:
      summary: Everything you can see about one role
      description: >-
        Use before drafting about role. roleId from listRecruiterRoles. When
        pitch.outreachTemplates not empty, base outreach on them; keep their
        wording and facts. When company.confidentialSearch true,
        candidate-facing copy names employer only as company.anonymizedName.
        pipeline.mySubmissions and summary.myRole.submissions are not agency
        totals.


        Required scopes: `roles:read`.
      operationId: getRecruiterRole
      parameters:
        - schema:
            type: string
            minLength: 1
            description: '`id` from listRecruiterRoles or listRecruiterActiveRoles row.'
          required: true
          description: '`id` from listRecruiterRoles or listRecruiterActiveRoles row.'
          name: roleId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    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
                    required:
                      - id
                      - name
                      - postedAt
                      - urls
                      - company
                      - locations
                      - workplaceType
                      - roleTypes
                      - techStack
                      - visaText
                      - compensation
                      - experience
                      - fee
                      - pipeline
                      - myRole
                      - recruiterAccess
                      - hiringManager
                  about:
                    type: object
                    properties:
                      description:
                        type: string
                        nullable: true
                      responsibilities:
                        type: array
                        items:
                          type: string
                      experience:
                        type: string
                        nullable: true
                      positionExplanation:
                        type: string
                        nullable: true
                      hiringGoals:
                        type: string
                        nullable: true
                      salaryDetail:
                        type: string
                        nullable: true
                    required:
                      - description
                      - responsibilities
                      - experience
                      - positionExplanation
                      - hiringGoals
                      - salaryDetail
                  requirements:
                    type: array
                    items:
                      type: object
                      properties:
                        description:
                          type: string
                        explanation:
                          type: string
                          nullable: true
                        type:
                          type: string
                      required:
                        - description
                        - explanation
                        - type
                  candidateTraits:
                    type: array
                    items:
                      type: string
                  avoidTraits:
                    type: array
                    items:
                      type: string
                  hiringManagerQuestions:
                    type: array
                    items:
                      type: object
                      properties:
                        question:
                          type: string
                        explanation:
                          type: string
                          nullable: true
                        optional:
                          type: boolean
                        recruiterOnly:
                          type: boolean
                        priority:
                          type: string
                          nullable: true
                      required:
                        - question
                        - explanation
                        - optional
                        - recruiterOnly
                        - priority
                  interviewProcess:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        description:
                          type: string
                          nullable: true
                      required:
                        - name
                        - description
                  pitch:
                    type: object
                    properties:
                      sellingPoints:
                        type: array
                        items:
                          type: object
                          properties:
                            title:
                              type: string
                            description:
                              type: string
                              nullable: true
                          required:
                            - title
                            - description
                      recruitingAdvice:
                        type: string
                        nullable: true
                      hiringManagerTip:
                        type: string
                        nullable: true
                      outreachGuidelines:
                        type: string
                        nullable: true
                      outreachHighlights:
                        type: array
                        items:
                          type: string
                      outreachResponsibilities:
                        type: string
                        nullable: true
                      recruiterSellingPoints:
                        type: string
                        nullable: true
                      candidateSellingPoints:
                        type: string
                        nullable: true
                      outreachTemplates:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              nullable: true
                            subject:
                              type: string
                              nullable: true
                            body:
                              type: string
                          required:
                            - name
                            - subject
                            - body
                      targetCompanies:
                        type: object
                        properties:
                          description:
                            type: string
                            nullable: true
                          goodFitCategories:
                            type: array
                            items:
                              type: string
                        required:
                          - description
                          - goodFitCategories
                      avoidCompanies:
                        type: object
                        properties:
                          badFitCategories:
                            type: array
                            items:
                              type: string
                        required:
                          - badFitCategories
                      calibrationProfiles:
                        type: array
                        items:
                          type: object
                          properties:
                            label:
                              type: string
                            note:
                              type: string
                              nullable: true
                          required:
                            - label
                            - note
                      faqs:
                        type: array
                        items:
                          type: object
                          properties:
                            question:
                              type: string
                            answer:
                              type: string
                              nullable: true
                          required:
                            - question
                            - answer
                      announcements:
                        type: array
                        items:
                          type: object
                          properties:
                            message:
                              type: string
                            createdAt:
                              type: string
                          required:
                            - message
                            - createdAt
                    required:
                      - sellingPoints
                      - recruitingAdvice
                      - hiringManagerTip
                      - outreachGuidelines
                      - outreachHighlights
                      - outreachResponsibilities
                      - recruiterSellingPoints
                      - candidateSellingPoints
                      - outreachTemplates
                      - targetCompanies
                      - avoidCompanies
                      - calibrationProfiles
                      - faqs
                      - announcements
                  company:
                    type: object
                    properties:
                      name:
                        type: string
                      confidentialSearch:
                        type: boolean
                      anonymizedName:
                        type: string
                        nullable: true
                      description:
                        type: string
                        nullable: true
                      teamAbout:
                        type: string
                        nullable: true
                      websiteUrl:
                        type: string
                        nullable: true
                      foundingYear:
                        type: number
                        nullable: true
                      fundingAmount:
                        type: string
                        nullable: true
                      totalFundingAmount:
                        type: string
                        nullable: true
                      lastFundingRound:
                        type: string
                        nullable: true
                      benefits:
                        type: array
                        items:
                          type: string
                      cultureValues:
                        type: array
                        items:
                          type: string
                    required:
                      - name
                      - confidentialSearch
                      - anonymizedName
                      - description
                      - teamAbout
                      - websiteUrl
                      - foundingYear
                      - fundingAmount
                      - totalFundingAmount
                      - lastFundingRound
                      - benefits
                      - cultureValues
                  pipeline:
                    type: object
                    properties:
                      stageCounts:
                        type: array
                        items:
                          type: object
                          properties:
                            stage:
                              type: string
                            count:
                              type: number
                          required:
                            - stage
                            - count
                      mySubmissions:
                        type: array
                        items:
                          type: object
                          properties:
                            candidateName:
                              type: string
                            currentStatus:
                              type: string
                            furthestStageReached:
                              type: string
                              nullable: true
                            rejectionReason:
                              type: string
                              nullable: true
                            statusUpdateMessage:
                              type: string
                              nullable: true
                          required:
                            - candidateName
                            - currentStatus
                            - furthestStageReached
                            - rejectionReason
                            - statusUpdateMessage
                      rejectionPatterns:
                        type: array
                        items:
                          type: object
                          properties:
                            category:
                              type: string
                            furthestStage:
                              type: string
                              nullable: true
                            reason:
                              type: string
                              nullable: true
                          required:
                            - category
                            - furthestStage
                            - reason
                    required:
                      - stageCounts
                      - mySubmissions
                      - rejectionPatterns
                required:
                  - summary
                  - about
                  - requirements
                  - candidateTraits
                  - avoidTraits
                  - hiringManagerQuestions
                  - interviewProcess
                  - pitch
                  - company
                  - pipeline
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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