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

# Read a role's recruiting brief

> Use for one role's full recruiting brief. roleId from listAgencyRoles or searchAgencyRoles; member need not be approved. When company.confidentialSearch true, name employer only as company.anonymizedName.

Required scopes: `agency_roles:read`.



## OpenAPI

````yaml /api/openapi.json get /agency/roles/{roleId}
openapi: 3.0.0
info:
  title: Paraform API
  version: v1
servers:
  - url: https://external-api.paraform.com/api/external/v1
security: []
paths:
  /agency/roles/{roleId}:
    get:
      summary: Read a role's recruiting brief
      description: >-
        Use for one role's full recruiting brief. roleId from listAgencyRoles or
        searchAgencyRoles; member need not be approved. When
        company.confidentialSearch true, name employer only as
        company.anonymizedName.


        Required scopes: `agency_roles:read`.
      operationId: getAgencyRole
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 128
            description: >-
              `id` from listAgencyRoles or searchAgencyRoles row. Never guess
              one.
          required: true
          description: '`id` from listAgencyRoles or searchAgencyRoles row. Never guess one.'
          name: roleId
          in: path
        - schema:
            type: string
            maxLength: 254
            format: email
            description: >-
              Email of currently approved member of your agency, e.g.
              jane@agency.com. Results use that member's permissions; does not
              authenticate key holder. Unknown, other-agency, or unapproved
              member answers 403.
          required: true
          description: >-
            Email of currently approved member of your agency, e.g.
            jane@agency.com. Results use that member's permissions; does not
            authenticate key holder. Unknown, other-agency, or unapproved member
            answers 403.
          name: recruiterEmail
          in: query
        - schema:
            anyOf:
              - type: string
                enum:
                  - 'true'
                  - 'false'
              - type: boolean
            description: >-
              Include role's intake call transcripts. Default false. Only
              transcripts this member may read returned.
          required: false
          description: >-
            Include role's intake call transcripts. Default false. Only
            transcripts this member may read returned.
          name: includeIntakeTranscripts
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
                  company:
                    type: object
                    properties:
                      id:
                        type: string
                        nullable: true
                      name:
                        type: string
                      confidentialSearch:
                        type: boolean
                      anonymizedName:
                        type: string
                        nullable: true
                      oneLiner:
                        type: string
                        nullable: true
                      description:
                        type: string
                        nullable: true
                      industries:
                        type: array
                        items:
                          type: string
                      size:
                        type: number
                        nullable: true
                      foundingYear:
                        type: number
                        nullable: true
                      teamAbout:
                        type: string
                        nullable: true
                      locations:
                        type: array
                        items:
                          type: string
                      officeLocations:
                        type: array
                        items:
                          type: string
                      websiteUrl:
                        type: string
                        nullable: true
                      linkedinUrl:
                        type: string
                        nullable: true
                      fundingAmount:
                        type: string
                        nullable: true
                      totalFundingAmount:
                        type: string
                        nullable: true
                      lastFundingRound:
                        type: string
                        nullable: true
                      fundingInfoUrl:
                        type: string
                        nullable: true
                      pressUrls:
                        type: array
                        items:
                          type: string
                      benefits:
                        type: array
                        items:
                          type: string
                      cultureValues:
                        type: array
                        items:
                          type: string
                      teamImageUrls:
                        type: array
                        items:
                          type: string
                      productImageUrls:
                        type: array
                        items:
                          type: string
                    required:
                      - id
                      - name
                      - confidentialSearch
                      - anonymizedName
                      - oneLiner
                      - description
                      - industries
                      - size
                      - foundingYear
                      - teamAbout
                      - locations
                      - officeLocations
                      - websiteUrl
                      - linkedinUrl
                      - fundingAmount
                      - totalFundingAmount
                      - lastFundingRound
                      - fundingInfoUrl
                      - pressUrls
                      - benefits
                      - cultureValues
                      - teamImageUrls
                      - productImageUrls
                    additionalProperties: false
                  status:
                    type: string
                    enum:
                      - ACTIVE
                      - PAUSED
                      - CLOSED
                  locations:
                    type: array
                    items:
                      type: string
                  workplaceType:
                    type: string
                    nullable: true
                    enum:
                      - REMOTE
                      - HYBRID
                      - ON_SITE
                  baseSalary:
                    type: object
                    nullable: true
                    properties:
                      currency:
                        type: string
                        nullable: true
                      min:
                        type: integer
                        nullable: true
                      max:
                        type: integer
                        nullable: true
                    required:
                      - currency
                      - min
                      - max
                    additionalProperties: false
                    description: >-
                      Annual candidate base salary, whole currency units, no
                      conversion. Null currency means unknown, not USD.
                  updatedAt:
                    type: string
                    format: date-time
                  description:
                    type: string
                    nullable: true
                  responsibilities:
                    type: array
                    items:
                      type: string
                  techStack:
                    type: array
                    items:
                      type: string
                  experience:
                    type: object
                    properties:
                      yearsMin:
                        type: number
                        nullable: true
                      yearsMax:
                        type: number
                        nullable: true
                      description:
                        type: string
                        nullable: true
                    required:
                      - yearsMin
                      - yearsMax
                      - description
                    additionalProperties: false
                  visaInformation:
                    type: string
                    nullable: true
                  equity:
                    type: string
                    nullable: true
                  salaryDetails:
                    type: string
                    nullable: true
                  positionExplanation:
                    type: string
                    nullable: true
                  hiringGoals:
                    type: string
                    nullable: true
                  workplaceDetails:
                    type: string
                    nullable: true
                  employmentType:
                    type: string
                    nullable: true
                  postedAt:
                    type: string
                    nullable: true
                    format: date-time
                  requirements:
                    type: array
                    items:
                      type: object
                      properties:
                        description:
                          type: string
                        explanation:
                          type: string
                          nullable: true
                        type:
                          type: string
                          enum:
                            - REQUIRED
                            - DEALBREAKER
                            - OPTIONAL
                            - YEARS_OF_EXPERIENCE
                        required:
                          type: boolean
                      required:
                        - description
                        - explanation
                        - type
                        - required
                      additionalProperties: false
                  interviewStages:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        description:
                          type: string
                          nullable: true
                      required:
                        - name
                        - description
                      additionalProperties: false
                  submissionQuestions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        question:
                          type: string
                        explanation:
                          type: string
                          nullable: true
                        required:
                          type: boolean
                        recruiterOnly:
                          type: boolean
                        priority:
                          type: string
                          nullable: true
                          enum:
                            - HIGH
                            - MEDIUM
                            - LOW
                      required:
                        - id
                        - question
                        - explanation
                        - required
                        - recruiterOnly
                        - priority
                      additionalProperties: false
                  recruitingGuidance:
                    type: object
                    properties:
                      sellingPoints:
                        type: array
                        items:
                          type: object
                          properties:
                            title:
                              type: string
                            description:
                              type: string
                              nullable: true
                          required:
                            - title
                            - description
                          additionalProperties: false
                      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
                          additionalProperties: false
                    required:
                      - sellingPoints
                      - recruitingAdvice
                      - hiringManagerTip
                      - outreachGuidelines
                      - outreachHighlights
                      - outreachResponsibilities
                      - recruiterSellingPoints
                      - candidateSellingPoints
                      - outreachTemplates
                    additionalProperties: false
                  candidateTargeting:
                    type: object
                    properties:
                      idealTraits:
                        type: array
                        items:
                          type: string
                      avoidTraits:
                        type: array
                        items:
                          type: string
                      idealCandidateDescription:
                        type: string
                        nullable: true
                        description: >-
                          Always null for now; not stored. Use idealTraits and
                          requirements.
                      targetCompanies:
                        type: object
                        properties:
                          description:
                            type: string
                            nullable: true
                          goodFitCategories:
                            type: array
                            items:
                              type: string
                        required:
                          - description
                          - goodFitCategories
                        additionalProperties: false
                      avoidCompanies:
                        type: object
                        properties:
                          badFitCategories:
                            type: array
                            items:
                              type: string
                        required:
                          - badFitCategories
                        additionalProperties: false
                    required:
                      - idealTraits
                      - avoidTraits
                      - idealCandidateDescription
                      - targetCompanies
                      - avoidCompanies
                    additionalProperties: false
                  additionalContext:
                    type: object
                    properties:
                      highlightTitle:
                        type: string
                        nullable: true
                      highlightDescription:
                        type: string
                        nullable: true
                      faqs:
                        type: array
                        items:
                          type: object
                          properties:
                            question:
                              type: string
                            answer:
                              type: string
                              nullable: true
                          required:
                            - question
                            - answer
                          additionalProperties: false
                      announcements:
                        type: array
                        items:
                          type: object
                          properties:
                            message:
                              type: string
                            createdAt:
                              type: string
                              format: date-time
                          required:
                            - message
                            - createdAt
                          additionalProperties: false
                    required:
                      - highlightTitle
                      - highlightDescription
                      - faqs
                      - announcements
                    additionalProperties: false
                  intakeTranscripts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                          nullable: true
                        recordedAt:
                          type: string
                          nullable: true
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                        text:
                          type: string
                        summary:
                          type: string
                          nullable: true
                      required:
                        - id
                        - title
                        - recordedAt
                        - updatedAt
                        - text
                        - summary
                      additionalProperties: false
                    description: >-
                      Absent unless requested. Empty when no selected, permitted
                      transcript text. Never has recording or playback URLs.
                required:
                  - id
                  - title
                  - company
                  - status
                  - locations
                  - workplaceType
                  - baseSalary
                  - updatedAt
                  - description
                  - responsibilities
                  - techStack
                  - experience
                  - visaInformation
                  - equity
                  - salaryDetails
                  - positionExplanation
                  - hiringGoals
                  - workplaceDetails
                  - employmentType
                  - postedAt
                  - requirements
                  - interviewStages
                  - submissionQuestions
                  - recruitingGuidance
                  - candidateTargeting
                  - additionalContext
                additionalProperties: false
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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