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

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

Returns one recruiter-facing role brief using the selected approved agency member's permissions. The role need not be in that member's approved-role list. Missing and inaccessible roles both return 404. Recruiter and company information is explicitly allowlisted; confidential/stealth views and announcement recipients are enforced server-side. Company logos and hiring-manager contact objects are excluded. Candidate calibration examples and application histories are excluded.

includeIntakeTranscripts defaults to false: the field is omitted and transcripts are not loaded. When true, the same agency\_roles:read scope includes only permitted transcripts selected by the role's intake settings. Hidden intake, restricted recruiters, private calls, unrelated-role calls, and unrevealed stealth identities do not unlock transcripts. Requested transcripts with no readable text return an empty array; summaries never substitute for transcript text. Recording, playback, and media-download URLs are not returned. Embedded links are omitted from prose.

Candidate salary/equity and company funding are included where visible. Structured recruiter-payment fields are excluded, but otherwise permitted prose is not screened for incidental payment mentions. Unknown or withheld scalar fields are null and collections are empty. updatedAt accounts for returned role, company, and guidance sources; each transcript has its own updatedAt. This API is independent of the talent network.

## Path parameters

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

## Query parameters

<ParamField query="recruiterEmail" type="string" required>
  Email of a currently approved member of the authenticated agency. Selects that member's permissions; it does not authenticate the person holding the key.
  Constraints: format `email`, max length 254.
</ParamField>

<ParamField query="includeIntakeTranscripts" type="string">
  Use true or false. Defaults to false. True includes only the intake transcripts permitted by the role's visibility and intake-selection rules.
  Allowed values: `true`, `false`.
</ParamField>

## Response

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

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

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

    <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="description" type="string | null" required />

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

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

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

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

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

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

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

    <ResponseField name="linkedinUrl" type="string | 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="fundingInfoUrl" type="string | null" required />

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

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

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

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

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

<ResponseField name="status" type="string" required>
  Allowed values: `ACTIVE`, `PAUSED`, `CLOSED`.
</ResponseField>

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

<ResponseField name="workplaceType" type="string | null" required>
  Allowed values: `REMOTE`, `HYBRID`, `ON_SITE`.
</ResponseField>

<ResponseField name="baseSalary" type="object | null" required>
  Annual candidate base salary in whole currency units, without conversion. Null currency is unknown, not implicitly USD.

  <Expandable title="baseSalary properties">
    <ResponseField name="currency" type="string | null" required />

    <ResponseField name="min" type="integer | null" required />

    <ResponseField name="max" type="integer | null" required />
  </Expandable>
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  Constraints: format `date-time`.
</ResponseField>

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

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

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

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

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

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

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

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

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

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

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

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

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

<ResponseField name="postedAt" type="string | null" required>
  Constraints: format `date-time`.
</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>
      Allowed values: `REQUIRED`, `DEALBREAKER`, `OPTIONAL`, `YEARS_OF_EXPERIENCE`.
    </ResponseField>

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

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

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

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

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

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

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

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

    <ResponseField name="priority" type="string | null" required>
      Allowed values: `HIGH`, `MEDIUM`, `LOW`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="recruitingGuidance" type="object" required>
  <Expandable title="recruitingGuidance 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>
  </Expandable>
</ResponseField>

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

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

    <ResponseField name="idealCandidateDescription" type="string | null" required>
      Currently null: a separate ideal-candidate description is not stored. Use idealTraits and the role requirements.
    </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>
  </Expandable>
</ResponseField>

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

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

    <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>
          Constraints: format `date-time`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="intakeTranscripts" type="object[]">
  Absent unless explicitly requested. Empty when no selected, permitted transcript text is available. Never contains recording or playback URLs.

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

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

    <ResponseField name="recordedAt" type="string | null" required>
      Constraints: format `date-time`.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      Constraints: format `date-time`.
    </ResponseField>

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

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

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "string",
    "title": "string",
    "company": {
      "id": "string",
      "name": "string",
      "confidentialSearch": true,
      "anonymizedName": "string",
      "oneLiner": "string",
      "description": "string",
      "industries": [
        "string"
      ],
      "size": 0,
      "foundingYear": 0,
      "teamAbout": "string",
      "locations": [
        "string"
      ],
      "officeLocations": [
        "string"
      ],
      "websiteUrl": "string",
      "linkedinUrl": "string",
      "fundingAmount": "string",
      "totalFundingAmount": "string",
      "lastFundingRound": "string",
      "fundingInfoUrl": "string",
      "pressUrls": [
        "string"
      ],
      "benefits": [
        "string"
      ],
      "cultureValues": [
        "string"
      ],
      "teamImageUrls": [
        "string"
      ],
      "productImageUrls": [
        "string"
      ]
    },
    "status": "ACTIVE",
    "locations": [
      "string"
    ],
    "workplaceType": "REMOTE",
    "baseSalary": {
      "currency": "string",
      "min": 0,
      "max": 0
    },
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "description": "string",
    "responsibilities": [
      "string"
    ],
    "techStack": [
      "string"
    ],
    "experience": {
      "yearsMin": 0,
      "yearsMax": 0,
      "description": "string"
    },
    "visaInformation": "string",
    "equity": "string",
    "salaryDetails": "string",
    "positionExplanation": "string",
    "hiringGoals": "string",
    "workplaceDetails": "string",
    "employmentType": "string",
    "postedAt": "2024-01-01T00:00:00.000Z",
    "requirements": [
      {
        "description": "string",
        "explanation": "string",
        "type": "REQUIRED",
        "required": true
      }
    ],
    "interviewStages": [
      {
        "name": "string",
        "description": "string"
      }
    ],
    "submissionQuestions": [
      {
        "id": "string",
        "question": "string",
        "explanation": "string",
        "required": true,
        "recruiterOnly": true,
        "priority": "HIGH"
      }
    ],
    "recruitingGuidance": {
      "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"
        }
      ]
    },
    "candidateTargeting": {
      "idealTraits": [
        "string"
      ],
      "avoidTraits": [
        "string"
      ],
      "idealCandidateDescription": "string",
      "targetCompanies": {
        "description": "string",
        "goodFitCategories": [
          "string"
        ]
      },
      "avoidCompanies": {
        "badFitCategories": [
          "string"
        ]
      }
    },
    "additionalContext": {
      "highlightTitle": "string",
      "highlightDescription": "string",
      "faqs": [
        {
          "question": "string",
          "answer": "string"
        }
      ],
      "announcements": [
        {
          "message": "string",
          "createdAt": "2024-01-01T00:00:00.000Z"
        }
      ]
    }
  }
  ```
</ResponseExample>


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