> ## Documentation Index
> Fetch the complete documentation index at: https://trygradient.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up your first AI hiring assessment

> Set up Gradient end to end: finish onboarding, add a role, get your assessment from Gradient, invite a candidate, and read their first score.

# Getting Started

This guide shows the full Gradient workflow. You finish onboarding, add your [role](/docs/concepts/roles),
and ask Gradient to build your assessment. Then you invite a candidate and review their score.

## Onboarding

When you first sign in, Gradient shows a short four-step onboarding. It ends at role creation:

<Steps>
  <Step title="Your details">
    Enter your name, your organization name (if you created the workspace), and your job role.
  </Step>

  <Step title="Candidate sandbox">
    See what the candidate experience looks like.
  </Step>

  <Step title="Scoring">
    Learn the scoring axes (deliverable, AI usage, durable skills) and session replay.
  </Step>

  <Step title="Get started">
    A recap of the three steps to your first assessment: add a role, Gradient builds your
    assessment, and you invite candidates. The wizard then takes you to add your first role.
  </Step>
</Steps>

## Prerequisites

* A Gradient account with admin access (owner or admin)
* At least one candidate to invite

## Step 1: Add your role

Everything starts from a role, the job you are hiring for.

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Roles** and click **Create role**.
    2. Enter a title and paste or link the job description.
    3. To import the role from your ATS, click **Import from ATS**. First connect your ATS (see
       [Integrations](/docs/integrations)).
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://app.trygradient.ai/api/roles \
      -H "Authorization: Bearer gai_your_key" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Senior Product Manager",
        "jdText": "We are hiring a senior PM to..."
      }'
    ```
  </Tab>
</Tabs>

## Step 2: Gradient builds your assessment

The Gradient team builds each assessment by hand. We write the task brief, the data candidates
search, and the scoring rubric for your role. You do not create or edit this content.

1. Email [hi@trygradient.ai](mailto:hi@trygradient.ai) with your role and what you want to test.
2. Gradient builds the assessment and adds it to your workspace.
3. Open the assessment and read the task. Tell us if you want a change.

<Note>
  Every assessment runs on the fixed Explore, Task, and Reflection phase model. Gradient sets the
  Task brief and time. See [Assessments](/docs/concepts/assessments#the-phase-model).
</Note>

When the assessment is in your workspace, you can change its settings. These include the name,
the due date, and feedback settings. See [Assessments](/docs/concepts/assessments).

## Step 3: Invite a candidate

<Tabs>
  <Tab title="Dashboard">
    1. Open the assessment.
    2. Click **Invite Candidate**.
    3. Enter their name and email. They receive an email with a unique assessment link.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://app.trygradient.ai/api/assessments/ASSESSMENT_ID/invite" \
      -H "Authorization: Bearer gai_your_key" \
      -H "Content-Type: application/json" \
      -d '{
        "email": "jane@example.com",
        "name": "Jane Smith"
      }'
    ```
  </Tab>
</Tabs>

To invite many candidates at once, see [Bulk invite](/docs/guides/bulk-invite).

## Step 4: Wait for submission

The candidate opens the link and moves through the Explore, Task, and optional Reflection
phases, then submits their deliverable (or it auto-submits when the Task timer ends). Check the
session status:

```bash theme={null}
curl "https://app.trygradient.ai/api/sessions?assessmentId=ASSESSMENT_ID&status=submitted" \
  -H "Authorization: Bearer gai_your_key"
```

## Step 5: Trigger scoring

Once a candidate submits, trigger the scoring engine:

```bash theme={null}
curl -X POST https://app.trygradient.ai/api/scoring \
  -H "Authorization: Bearer gai_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "SESSION_ID"}'
```

## Step 6: Review results

Retrieve the score breakdown:

```bash theme={null}
curl "https://app.trygradient.ai/api/scoring/SESSION_ID" \
  -H "Authorization: Bearer gai_your_key"
```

The response includes category scores with point breakdowns, a percentile ranking against other
candidates who sat the same assessment, summary text, and suggested follow-up questions. You can also review the full
session in the dashboard, including session replay, the AI conversation transcript, and the
candidate's workspace configuration. See [Scoring](/docs/concepts/scoring) for how scores are
computed.


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