> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.studyhq.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.studyhq.com/_mcp/server.

# Quick Start

> Integrate StudyHQ assessments in three steps — authenticate, generate a student's assessment link, and fetch their results.

Get up and running with the StudyHQ Partner API in minutes: **authenticate**,
**generate** a student's assessment link, and **fetch** their results.

---

## Prerequisites

Before you begin, make sure you have:

* A StudyHQ partner account (contact [support@studyhq.com](mailto:support@studyhq.com) to get onboarded)
* Your project's `TokenId` and `TokenSecret`
* Your `projectId` (provided during onboarding)

---

## Authenticate

The Partner API uses **token-based authentication**. Tokens are issued per project
during onboarding as a pair of credentials:

| Credential    | Description                                               |
| ------------- | --------------------------------------------------------- |
| `TokenId`     | Public identifier for the token                           |
| `TokenSecret` | Secret used to authenticate — shown only once at creation |

> **Warning**
>
> The `TokenSecret` is shown only once when the token is created. Store it
> securely — if it's lost, the token must be regenerated.

Include the token in **every** request via the `X-Access-Token` header, formatted as
`TokenId:TokenSecret`:

| Header           | Value                     |
| ---------------- | ------------------------- |
| `X-Access-Token` | `<TokenId>:<TokenSecret>` |
| `Content-Type`   | `application/json`        |
| `Accept`         | `application/json`        |

---

## Step 1 — Generate an assessment URL

After a student registers (or completes payment) on your platform, call the API to
generate a unique assessment link.

```bash
curl -X POST https://api.studyhq.com/partner/get-redirect-url \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: <TokenId>:<TokenSecret>" \
  -d '{
    "projectId": "L4ndb5PYxM",
    "name": "Student name",
    "email": "student@gmail.com",
    "mobile": "9876543210"
  }'
```

**Response:**

```json
{
  "redirect-url": "https://app.studyhq.com/L4ndb5PYxM/assessment?token=eyJhbGciOiJSU..."
}
```

Open the `redirect-url` in a new tab for the student to begin the assessment.

> **Note**
>
> The redirect URL is time-bound and single-use. Generate a fresh URL each time a
> student needs to take the assessment.

---

## Step 2 — Student completes the assessment

The student takes the assessment on StudyHQ. Results are stored against their email.

| Status      | Meaning                         |
| ----------- | ------------------------------- |
| `Completed` | Student finished the assessment |
| `Abandoned` | Student did not finish          |

---

## Step 3 — Fetch results

Once the student has completed the assessment, retrieve their results and course
recommendations.

```bash
curl -X POST https://api.studyhq.com/partner/get-assessments-info \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: <TokenId>:<TokenSecret>" \
  -d '{
    "projectId": "L4ndb5PYxM",
    "email": "student@gmail.com"
  }'
```

**Response:**

```json
[
  {
    "AssessmentId": "AnE9YIqu5plq",
    "Status": "Completed",
    "Recommendations": [
      "Fashion Design",
      "Entrepreneurship & Family Business"
    ],
    "AssessmentDuration": "1m 58s"
  }
]
```

Use the `Recommendations` array to display personalised course options to the
student on your platform.

---

## Token lifecycle & security

| Event         | Behaviour                                  |
| ------------- | ------------------------------------------ |
| Token created | Secret is shown once — copy it immediately |
| Secret lost   | Token must be deleted and regenerated      |
| Token revoked | Requests using that token fail with `401`  |
| Token scope   | Restricted to a single project             |

**Best practices**

* Never expose the `X-Access-Token` header in client-side code or browser requests.
* Don't log raw request headers in your application.
* Rotate tokens periodically, or immediately if compromised.
* Contact [support@studyhq.com](mailto:support@studyhq.com) for token revocation or rotation.

---

## What's next

#### [Partner Workflow](/documentation/integration-guide/partner-workflow)

The end-to-end integration flow for CRM and admissions platforms.

#### [Enrollment Sync](/documentation/integration-guide/enrollment-sync)

Keep StudyHQ in sync when a student converts to an enrolled admission.