Getting Started

This guide walks you through the full Gradient workflow: onboarding, creating your first role, 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:

Your details

Enter your name, your organization name (if you created the workspace), and your job role.

Candidate sandbox

See what the candidate experience looks like.

Scoring

Learn the scoring axes (deliverable, AI usage, durable skills) and session replay.

Calibration

Learn what happens after an assessment: feedback that refines the rubric, follow-up interview questions, and optional candidate feedback.

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.

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.

Dashboard
API

Go to Roles and click Create role.
Enter a title and paste or link the job description. You can also Import from ATS if you have connected one (see Integrations).
Confirm the priority skills Gradient suggests from the job description.

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..."
  }'

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

Dashboard
API

From the role, choose a suggested assessment or start from a custom brief.
In the build wizard, set the task brief and deliverable type, then move through the Data, settings, reflection, and rubric steps.
Publish the assessment to make it active.

The API create path is lower level than the role-first UI. It accepts the task directly:

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
  }'

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.

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:

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

Dashboard
API

Open the assessment.
Click Invite Candidate.
Enter their name and email. They receive an email with a unique assessment link.

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"
  }'

To invite many candidates at once, see 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:

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:

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:

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 for how scores are computed.

​Getting Started

​Onboarding

​Prerequisites

​Step 1: Create a role

​Step 2: Build an assessment

​Step 3: Add data sources

​Step 4: Invite a candidate

​Step 5: Wait for submission

​Step 6: Trigger scoring

​Step 7: Review results

Getting Started

Onboarding

Prerequisites

Step 1: Create a role

Step 2: Build an assessment

Step 3: Add data sources

Step 4: Invite a candidate

Step 5: Wait for submission

Step 6: Trigger scoring

Step 7: Review results