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

<Info>
  **Required scopes:** `roles:read`<br />
  **Rate limit:** `default` tier, 120 requests per minute per key
</Info>

The full role page a recruiter sees on Paraform, in one call: the hiring manager's description and requirements, the questions you must answer about a candidate when you submit, the interview stages, selling points and outreach guidance, the company pitch, anonymized pipeline and rejection history, and your own submissions to the role. `summary` repeats the `listRecruiterRoles` row so fee, competition, hiring manager engagement and your slot status are here too.

Outreach material is in `pitch.outreachGuidelines` and `pitch.outreachHighlights` (the hiring manager's own guidance, when set), `pitch.candidateSellingPoints`, `pitch.sellingPoints`, `pitch.recruitingAdvice`, `pitch.outreachTemplates` and `company`. Screening material is in `hiringManagerQuestions`, `requirements` and `interviewProcess`, and submission context in `requirements`, `pipeline.rejectionPatterns` and `pitch.calibrationProfiles`.

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

`pipeline.mySubmissions` is capped at the 30 newest and, for an agency owner, includes the agency's submissions, so its length is not a total. `summary.myRole.submissions` counts only your own applications, so it is not an agency total either.

`roleId` is the `id` from `listRecruiterRoles`. A role you cannot work on returns 404.

## Path parameters

<ParamField path="roleId" type="string" required>
  Constraints: min length 1.
</ParamField>

## Response

<ResponseField name="summary" type="object" required>
  <Expandable title="summary properties">
    <ResponseField name="id" type="string" required />

    <ResponseField name="name" type="string" required />

    <ResponseField name="postedAt" type="string | null" required />

    <ResponseField name="urls" type="object" required>
      <Expandable title="urls properties">
        <ResponseField name="browse" type="string" required />

        <ResponseField name="recruit" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="company" type="object" required>
      <Expandable title="company properties">
        <ResponseField name="name" type="string" required />

        <ResponseField name="confidentialSearch" type="boolean" required />

        <ResponseField name="anonymizedName" type="string | null" required />

        <ResponseField name="oneLiner" type="string | null" required />

        <ResponseField name="industries" type="string[]" required />

        <ResponseField name="size" type="number | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="locations" type="string[]" required />

    <ResponseField name="workplaceType" type="string | null" required />

    <ResponseField name="roleTypes" type="string[]" required />

    <ResponseField name="techStack" type="string[]" required />

    <ResponseField name="visaText" type="string | null" required />

    <ResponseField name="compensation" type="object" required>
      <Expandable title="compensation properties">
        <ResponseField name="salaryLowerBound" type="number" required />

        <ResponseField name="salaryUpperBound" type="number" required />

        <ResponseField name="currency" type="string | null" required />

        <ResponseField name="equity" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="experience" type="object" required>
      <Expandable title="experience properties">
        <ResponseField name="yearsMin" type="number" required />

        <ResponseField name="yearsMax" type="number | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="fee" type="object" required>
      <Expandable title="fee properties">
        <ResponseField name="amountLowerBound" type="number | null" required />

        <ResponseField name="percentOfSalary" type="number | null" required />

        <ResponseField name="boostPercent" type="number | null" required />

        <ResponseField name="bonusAmount" type="number | null" required />

        <ResponseField name="firstSubmissionReward" type="number | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="pipeline" type="object" required>
      <Expandable title="pipeline properties">
        <ResponseField name="totalApplications" type="number | null" required />

        <ResponseField name="totalInterviewing" type="number" required />

        <ResponseField name="totalHired" type="number" required />

        <ResponseField name="openingsText" type="string" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="myRole" type="object" required>
      <Expandable title="myRole properties">
        <ResponseField name="isApproved" type="boolean" required />

        <ResponseField name="isPrimary" type="boolean" required />

        <ResponseField name="accessLevel" type="string | null" required />

        <ResponseField name="approvalStatus" type="string | null" required />

        <ResponseField name="submissions" type="object" required>
          <Expandable title="submissions properties">
            <ResponseField name="submitted" type="number" required />

            <ResponseField name="interviewing" type="number" required />

            <ResponseField name="hired" type="number" required />

            <ResponseField name="total" type="number" required />
          </Expandable>
        </ResponseField>

        <ResponseField name="trial" type="object | null" required>
          <Expandable title="trial properties">
            <ResponseField name="endsAt" type="string | null" required />

            <ResponseField name="businessDaysLeft" type="number | null" required />

            <ResponseField name="submissionGoal" type="number" required />

            <ResponseField name="submissionsCounted" type="number" required />

            <ResponseField name="isActive" type="boolean" required />

            <ResponseField name="endingSoon" type="boolean" required />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="recruiterAccess" type="object" required>
      <Expandable title="recruiterAccess properties">
        <ResponseField name="atMaxCapacity" type="boolean" required />

        <ResponseField name="notAcceptingRecruiters" type="boolean" required />

        <ResponseField name="density" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="hiringManager" type="object" required>
      <Expandable title="hiringManager properties">
        <ResponseField name="lastActiveAt" type="string | null" required />

        <ResponseField name="responsivenessDays" type="number" required />

        <ResponseField name="engagement" type="object | null" required>
          <Expandable title="engagement properties">
            <ResponseField name="finalRating" type="number | null" required />

            <ResponseField name="percentileRank" type="number | null" required />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="about" type="object" required>
  <Expandable title="about properties">
    <ResponseField name="description" type="string | null" required />

    <ResponseField name="responsibilities" type="string[]" required />

    <ResponseField name="experience" type="string | null" required />

    <ResponseField name="positionExplanation" type="string | null" required />

    <ResponseField name="hiringGoals" type="string | null" required />

    <ResponseField name="salaryDetail" type="string | null" required />
  </Expandable>
</ResponseField>

<ResponseField name="requirements" type="object[]" required>
  <Expandable title="requirements properties">
    <ResponseField name="description" type="string" required />

    <ResponseField name="explanation" type="string | null" required />

    <ResponseField name="type" type="string" required />
  </Expandable>
</ResponseField>

<ResponseField name="candidateTraits" type="string[]" required />

<ResponseField name="avoidTraits" type="string[]" required />

<ResponseField name="hiringManagerQuestions" type="object[]" required>
  <Expandable title="hiringManagerQuestions properties">
    <ResponseField name="question" type="string" required />

    <ResponseField name="explanation" type="string | null" required />

    <ResponseField name="optional" type="boolean" required />

    <ResponseField name="recruiterOnly" type="boolean" required />

    <ResponseField name="priority" type="string | null" required />
  </Expandable>
</ResponseField>

<ResponseField name="interviewProcess" type="object[]" required>
  <Expandable title="interviewProcess properties">
    <ResponseField name="name" type="string" required />

    <ResponseField name="description" type="string | null" required />
  </Expandable>
</ResponseField>

<ResponseField name="pitch" type="object" required>
  <Expandable title="pitch properties">
    <ResponseField name="sellingPoints" type="object[]" required>
      <Expandable title="sellingPoints properties">
        <ResponseField name="title" type="string" required />

        <ResponseField name="description" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="recruitingAdvice" type="string | null" required />

    <ResponseField name="hiringManagerTip" type="string | null" required />

    <ResponseField name="outreachGuidelines" type="string | null" required />

    <ResponseField name="outreachHighlights" type="string[]" required />

    <ResponseField name="outreachResponsibilities" type="string | null" required />

    <ResponseField name="recruiterSellingPoints" type="string | null" required />

    <ResponseField name="candidateSellingPoints" type="string | null" required />

    <ResponseField name="outreachTemplates" type="object[]" required>
      <Expandable title="outreachTemplates properties">
        <ResponseField name="name" type="string | null" required />

        <ResponseField name="subject" type="string | null" required />

        <ResponseField name="body" type="string" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="targetCompanies" type="object" required>
      <Expandable title="targetCompanies properties">
        <ResponseField name="description" type="string | null" required />

        <ResponseField name="goodFitCategories" type="string[]" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="avoidCompanies" type="object" required>
      <Expandable title="avoidCompanies properties">
        <ResponseField name="badFitCategories" type="string[]" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="calibrationProfiles" type="object[]" required>
      <Expandable title="calibrationProfiles properties">
        <ResponseField name="label" type="string" required />

        <ResponseField name="note" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="faqs" type="object[]" required>
      <Expandable title="faqs properties">
        <ResponseField name="question" type="string" required />

        <ResponseField name="answer" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="announcements" type="object[]" required>
      <Expandable title="announcements properties">
        <ResponseField name="message" type="string" required />

        <ResponseField name="createdAt" type="string" required />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="company" type="object" required>
  <Expandable title="company properties">
    <ResponseField name="name" type="string" required />

    <ResponseField name="confidentialSearch" type="boolean" required />

    <ResponseField name="anonymizedName" type="string | null" required />

    <ResponseField name="description" type="string | null" required />

    <ResponseField name="teamAbout" type="string | null" required />

    <ResponseField name="websiteUrl" type="string | null" required />

    <ResponseField name="foundingYear" type="number | null" required />

    <ResponseField name="fundingAmount" type="string | null" required />

    <ResponseField name="totalFundingAmount" type="string | null" required />

    <ResponseField name="lastFundingRound" type="string | null" required />

    <ResponseField name="benefits" type="string[]" required />

    <ResponseField name="cultureValues" type="string[]" required />
  </Expandable>
</ResponseField>

<ResponseField name="pipeline" type="object" required>
  <Expandable title="pipeline properties">
    <ResponseField name="stageCounts" type="object[]" required>
      <Expandable title="stageCounts properties">
        <ResponseField name="stage" type="string" required />

        <ResponseField name="count" type="number" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="mySubmissions" type="object[]" required>
      <Expandable title="mySubmissions properties">
        <ResponseField name="candidateName" type="string" required />

        <ResponseField name="currentStatus" type="string" required />

        <ResponseField name="furthestStageReached" type="string | null" required />

        <ResponseField name="rejectionReason" type="string | null" required />

        <ResponseField name="statusUpdateMessage" type="string | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="rejectionPatterns" type="object[]" required>
      <Expandable title="rejectionPatterns properties">
        <ResponseField name="category" type="string" required />

        <ResponseField name="furthestStage" type="string | null" required />

        <ResponseField name="reason" type="string | null" required />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://external-api.paraform.com/api/external/v1/recruiter/roles/$ROLE_ID" \
    -H "Authorization: Bearer $PARAFORM_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "summary": {
      "id": "string",
      "name": "string",
      "postedAt": "string",
      "urls": {
        "browse": "string",
        "recruit": "string"
      },
      "company": {
        "name": "string",
        "confidentialSearch": true,
        "anonymizedName": "string",
        "oneLiner": "string",
        "industries": [
          "string"
        ],
        "size": 0
      },
      "locations": [
        "string"
      ],
      "workplaceType": "string",
      "roleTypes": [
        "string"
      ],
      "techStack": [
        "string"
      ],
      "visaText": "string",
      "compensation": {
        "salaryLowerBound": 0,
        "salaryUpperBound": 0,
        "currency": "string",
        "equity": "string"
      },
      "experience": {
        "yearsMin": 0,
        "yearsMax": 0
      },
      "fee": {
        "amountLowerBound": 0,
        "percentOfSalary": 0,
        "boostPercent": 0,
        "bonusAmount": 0,
        "firstSubmissionReward": 0
      },
      "pipeline": {
        "totalApplications": 0,
        "totalInterviewing": 0,
        "totalHired": 0,
        "openingsText": "string"
      },
      "myRole": {
        "isApproved": true,
        "isPrimary": true,
        "accessLevel": "string",
        "approvalStatus": "string",
        "submissions": {
          "submitted": 0,
          "interviewing": 0,
          "hired": 0,
          "total": 0
        },
        "trial": {
          "endsAt": "string",
          "businessDaysLeft": 0,
          "submissionGoal": 0,
          "submissionsCounted": 0,
          "isActive": true,
          "endingSoon": true
        }
      },
      "recruiterAccess": {
        "atMaxCapacity": true,
        "notAcceptingRecruiters": true,
        "density": "string"
      },
      "hiringManager": {
        "lastActiveAt": "string",
        "responsivenessDays": 0,
        "engagement": {
          "finalRating": 0,
          "percentileRank": 0
        }
      }
    },
    "about": {
      "description": "string",
      "responsibilities": [
        "string"
      ],
      "experience": "string",
      "positionExplanation": "string",
      "hiringGoals": "string",
      "salaryDetail": "string"
    },
    "requirements": [
      {
        "description": "string",
        "explanation": "string",
        "type": "string"
      }
    ],
    "candidateTraits": [
      "string"
    ],
    "avoidTraits": [
      "string"
    ],
    "hiringManagerQuestions": [
      {
        "question": "string",
        "explanation": "string",
        "optional": true,
        "recruiterOnly": true,
        "priority": "string"
      }
    ],
    "interviewProcess": [
      {
        "name": "string",
        "description": "string"
      }
    ],
    "pitch": {
      "sellingPoints": [
        {
          "title": "string",
          "description": "string"
        }
      ],
      "recruitingAdvice": "string",
      "hiringManagerTip": "string",
      "outreachGuidelines": "string",
      "outreachHighlights": [
        "string"
      ],
      "outreachResponsibilities": "string",
      "recruiterSellingPoints": "string",
      "candidateSellingPoints": "string",
      "outreachTemplates": [
        {
          "name": "string",
          "subject": "string",
          "body": "string"
        }
      ],
      "targetCompanies": {
        "description": "string",
        "goodFitCategories": [
          "string"
        ]
      },
      "avoidCompanies": {
        "badFitCategories": [
          "string"
        ]
      },
      "calibrationProfiles": [
        {
          "label": "string",
          "note": "string"
        }
      ],
      "faqs": [
        {
          "question": "string",
          "answer": "string"
        }
      ],
      "announcements": [
        {
          "message": "string",
          "createdAt": "string"
        }
      ]
    },
    "company": {
      "name": "string",
      "confidentialSearch": true,
      "anonymizedName": "string",
      "description": "string",
      "teamAbout": "string",
      "websiteUrl": "string",
      "foundingYear": 0,
      "fundingAmount": "string",
      "totalFundingAmount": "string",
      "lastFundingRound": "string",
      "benefits": [
        "string"
      ],
      "cultureValues": [
        "string"
      ]
    },
    "pipeline": {
      "stageCounts": [
        {
          "stage": "string",
          "count": 0
        }
      ],
      "mySubmissions": [
        {
          "candidateName": "string",
          "currentStatus": "string",
          "furthestStageReached": "string",
          "rejectionReason": "string",
          "statusUpdateMessage": "string"
        }
      ],
      "rejectionPatterns": [
        {
          "category": "string",
          "furthestStage": "string",
          "reason": "string"
        }
      ]
    }
  }
  ```
</ResponseExample>


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