Skip to main content
Braintest is a psychological testing platform that lets partners administer validated tests (MCMI, NEO, DASS-21, PHQ-9, and more) and AI-powered cognitive roadmaps through a single REST API. Whether you are building a wellness app, a counseling platform, or an HR assessment tool, you can embed Braintest tests and retrieve results without managing test content or scoring logic yourself.

Quickstart

Get your first test result in minutes with a step-by-step walkthrough.

Authentication

Learn how to obtain and use your API key to authenticate requests.

Records

Understand standalone test records, their lifecycle, and status codes.

Roadmaps

Explore multi-test packages with AI-powered combined analysis.

​
Integration patterns

The Braintest API supports two main integration patterns. Choose the one that fits your use case. Every record and roadmap payload includes a tests_auth_required flag copied from your organizer setting. It controls whether authentication uses a two-step SMS flow (default) or completes on a single call.

​
Standalone tests

Use this pattern when you want to administer a single psychological test to a participant.
  1. List available records and pick one with status: 2 (ready) and auth_required: true.
  2. Call POST /record/{token}/auth/ with the participant profile.
  3. When tests_auth_required is true, finish authentication by calling PUT /record/{token}/auth/verify/ with the returned draft_token and the SMS code. When it is false, the profile is created immediately.
  4. Fetch the test questions.
  5. Submit the participant answers.
  6. Retrieve the result in JSON or HTML format.

​
Cognitive roadmaps

Use this pattern when you want to run a multi-test package and receive an AI-generated combined analysis.
  1. List available roadmaps and pick one with status: 2 (ready).
  2. Call POST /roadmap/{token}/auth/ with the shared mobile and one profile per role.
  3. When tests_auth_required is true, finish authentication by calling PUT /roadmap/{token}/auth/verify/ with the draft_token and the SMS code. When it is false, all role profiles are created immediately.
  4. For each test record in the roadmap, fetch questions and submit answers.
  5. Queue AI analysis generation.
  6. Poll the generation status until it completes.
  7. Retrieve the combined roadmap result in JSON or HTML format.
For roadmap records, always authenticate through /roadmap/{token}/auth/ instead of /record/{token}/auth/. Roadmap authentication links all participant profiles to every record in the package automatically.