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

# Partner Workflow

> End-to-end integration flow for embedding StudyHQ assessments into your platform.

This guide describes the end-to-end flow for integrating StudyHQ assessments into a partner platform such as a CRM, admissions portal, or EdTech product.

---

## Overview

StudyHQ supports two primary integration patterns depending on where in your funnel the assessment takes place.

### Option A — Assessment Before Application

The student takes the assessment immediately after registration. Based on their results, they are shown recommended courses and prompted to complete the application.

```
Student registers
      ↓
Partner generates assessment URL  →  Student takes assessment
      ↓
Recommended courses shown
      ↓
Student completes application form
```

### Option B — Assessment After Payment

The student completes the application and payment first. The assessment is unlocked as a next step post-payment.

```
Student submits application form
      ↓
Payment of ₹1,000 collected
      ↓
Partner generates assessment URL  →  Student takes assessment
      ↓
Recommended courses shown
```

---

## Detailed Flow

#### Student Arrives on Partner Platform

The student lands on your platform (e.g. via landing page), registers, and
enters the CRM dashboard.

#### Trigger Assessment

Based on your chosen workflow (Option A or B), your backend calls `POST
    /partner/get-redirect-url` with the student's details to generate a unique
assessment link.

#### Student Takes Assessment

Open the `redirect-url` in a new tab. The student completes or abandons the
test on StudyHQ. No session management is required on your end.

#### Fetch Results

Call `POST /partner/get-assessments-info` with the student's email to
retrieve their assessment status, duration, and recommended courses.

#### Display Recommendations

Use the `Recommendations` array to surface personalised course options
inside your platform's dashboard or application flow.

---

## API Reference Summary

| Endpoint                             | Purpose                                                  |
| ------------------------------------ | -------------------------------------------------------- |
| `POST /partner/get-redirect-url`     | Generate a time-bound assessment URL for a student       |
| `POST /partner/get-assessments-info` | Retrieve assessment results and recommendations by email |

---

## Error Handling

| HTTP Status | Meaning                   | Suggested Action                                         |
| ----------- | ------------------------- | -------------------------------------------------------- |
| `400`       | Missing or invalid fields | Validate request payload before sending                  |
| `401`       | Invalid or revoked token  | Check token credentials or request a new token           |
| `429`       | Rate limit exceeded       | Implement exponential backoff and retry                  |
| `500`       | Internal server error     | Retry after a short delay; contact support if persistent |

---

> **Note**
>
> Assessment URLs are time-bound and single-use. Always generate a fresh URL
> each time a student needs to attempt the assessment — do not cache or reuse
> previous URLs.