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

# Getting Started

> From onboarding to your first scored candidate

# Getting Started

This guide walks you through the full Gradient workflow: onboarding, creating your first
[role](/concepts/roles), building an assessment under it, inviting a candidate, and reviewing
their score.

## Onboarding

When you first sign in, Gradient runs a short five-step onboarding that introduces the product
and ends by dropping you into 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="Calibration">
    Learn what happens after an assessment: feedback that refines the rubric, follow-up
    interview questions, and optional candidate feedback.
  </Step>

  <Step title="Get started">
    A recap of the three steps to your first assessment: create a role, build an assessment,
    invite candidates. The wizard finishes by taking you to create your first role.
  </Step>
</Steps>

## Prerequisites

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

## Step 1: Create a 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. You can also **Import from ATS** if
       you have connected one (see [Integrations](/integrations)).
    3. Confirm the priority skills Gradient suggests from the job description.
  </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: Build an assessment

From the role, design the assessment candidates will complete. Gradient can suggest a first
draft from the role's job description, which you then refine in the build wizard (task brief,
Data step, settings, optional reflection, and rubric).

<Tabs>
  <Tab title="Dashboard">
    1. From the role, choose a suggested assessment or start from a custom brief.
    2. In the build wizard, set the task brief and deliverable type, then move through the
       Data, settings, reflection, and rubric steps.
    3. Publish the assessment to make it active.
  </Tab>

  <Tab title="API">
    The API create path is lower level than the role-first UI. It accepts the task directly:

    ```bash theme={null}
    curl -X POST https://app.trygradient.ai/api/assessments/create \
      -H "Authorization: Bearer gai_your_key" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Senior PM Assessment",
        "role": "Senior Product Manager",
        "taskPrompt": "Create a product strategy presentation for entering the European market. Use the available data sources to support your recommendations.",
        "deliverableType": "pptx",
        "taskTimeMinutes": 50
      }'
    ```
  </Tab>
</Tabs>

<Note>
  Every assessment runs on the fixed Explore, Task, and Reflection phase model. You set the Task
  brief and time; Explore (5 minutes) and Reflection (10 minutes, optional) are fixed. See
  [Assessments](/concepts/assessments#the-phase-model).
</Note>

## Step 3: Add data sources

Seed the documents candidates can search during the assessment, and mark some as **signal**
(relevant) and others as **noise** (distractors). In the dashboard, this is the build wizard's
**Data** step. Via the API, attach inline files to a connector:

```bash theme={null}
curl -X POST "https://app.trygradient.ai/api/assessments/ASSESSMENT_ID/connector-data" \
  -H "Authorization: Bearer gai_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorType": "enterprise_search",
    "name": "Q3 Revenue Report",
    "isSignal": true,
    "dataFiles": [
      { "title": "q3-revenue.md", "content": "Revenue by region..." }
    ]
  }'
```

## Step 4: 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](/guides/bulk-invite).

## Step 5: 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 6: 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 7: 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, percentile rankings against other
candidates, 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](/concepts/scoring) for how scores are
computed.