Skip to main content
A cognitive roadmap is a curated package of multiple psychological tests bundled together and analyzed as a whole. Unlike standalone records, which return a single test score, roadmaps feed all participant answers into an AI model that produces a combined, narrative analysis across tests.

​
What a roadmap contains

Each roadmap defines:
  • A set of test records (e.g., MCMI + NEO + DASS-21)
  • Required participant roles (who takes which tests)
  • An AI analysis module that runs after all tests are complete
Roadmaps are ideal for use cases that need holistic insight, such as pre-marital counseling, comprehensive clinical intake, or executive coaching assessments.

​
Participant roles

Every roadmap declares the roles it requires. Common examples include: When you authenticate a roadmap, you provide one profile per required role. The API then links each profile to the correct subset of records automatically.

​
Roadmap status codes

​
Authentication difference

Roadmap records must be authenticated through the roadmap endpoint, not the record endpoint.
  • Correct: POST /roadmap/{token}/auth/
  • Incorrect: POST /record/{token}/auth/ (will fail for roadmap records)
A single call to /roadmap/{token}/auth/ starts the authentication flow for all required profiles and links them to every record in the package. You do not need to call auth for each record individually. The organizer setting tests_auth_required (echoed in every roadmap and nested test record) determines the flow:
  • true (default): the auth call sends an SMS code to the shared mobile and returns a draft_token. Finish the flow by calling PUT /roadmap/{token}/auth/verify/ with the code.
  • false: the auth call authenticates all role profiles immediately and returns them in the response.

​
AI generation

After all tests in a roadmap are finished, you must explicitly queue the AI analysis:
  1. Call POST /roadmap/{token}/generate/ to start the analysis job.
  2. Poll GET /roadmap/{token}/generate/status/ until the status is completed or failed.
  3. The generation typically takes 5 to 10 minutes.
Do not skip the generation step. Roadmap results are not available until the AI analysis job finishes successfully.

​
Result formats

Once generation is complete, retrieve the combined result:
  • GET /roadmap/{token}/result/json/ for structured data
  • GET /roadmap/{token}/result/html/ for a rendered report