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

# Your recommended submissions, across every candidate in your CRM

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

The "Recommended submissions" list from your Paraform home page: for every candidate in your CRM, the roles Paraform's matching model recommends you submit them to. Candidates come in order of their strongest pair, and each candidate's roles come strongest first. Recruiters also call these "single sub recs", because most are roles where you would submit without holding a primary slot.

Use this for questions across the whole CRM, such as "review my single sub recs and tell me which to act on". For one named candidate use `listRecommendedRolesForCandidate` instead. Never answer the whole-CRM question by looping that endpoint over every candidate: this call returns the same rows at once.

Pairs are ranked ENDORSED before SUGGESTED and by match strength inside each band. The list already leaves out candidates hired recently, roles the candidate was already submitted to, and roles you cannot submit to. Every role carries the full `listRecruiterRoles` shape, so you can rank by payout, competition and whether you hold the slot.

This read returns at most 20 (candidate, role) pairs, the strongest first. An empty list with `enabled` true means Paraform has no active recommendation for any of your candidates right now.

## Query parameters

<ParamField query="limit" type="integer" default={"20"}>
  Constraints: minimum 1.
</ParamField>

## Response

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

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

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

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

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

    <ResponseField name="roles" type="object[]" required>
      <Expandable title="roles 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>

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

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "enabled": true,
    "candidates": [
      {
        "candidateId": "string",
        "name": "string",
        "title": "string",
        "linkedinUrl": "string",
        "roles": [
          {}
        ]
      }
    ]
  }
  ```
</ResponseExample>


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