Skip to main content
A profile represents a single test participant in the Braintest platform. It stores demographic and contact data that link a real person to their test records and roadmap results. Braintest supports two authentication paths, selected by the organizer setting tests_auth_required and echoed on every record and roadmap payload.

​
Required fields

Every profile must include the following fields when calling an authentication endpoint:

​
Optional fields

​
Authentication paths

The organizer setting tests_auth_required (visible on every record and roadmap payload) selects the flow. Your integration should always read the flag from the resource and branch on it.

​
Path A: SMS verification (tests_auth_required: true, default)

  1. POST /record/{token}/auth/ or POST /roadmap/{token}/auth/ with the profile data.
  2. The API validates the fields, sends an SMS code to the participant’s mobile, and returns a draft_token.
  3. Prompt the participant for the code and call PUT /.../auth/verify/ with the draft_token and vcode.
  4. On success, the API returns the final profile (or role profiles) and links them to the record or every record in the roadmap.
Draft tokens expire after 5 minutes. Requesting new codes is throttled per mobile, and mobile numbers that hit the per-account duplicate limit receive a 400 error.

​
Path B: Instant (tests_auth_required: false)

  1. POST /record/{token}/auth/ or POST /roadmap/{token}/auth/ with the profile data.
  2. If validation passes, the profile is created (or matched by external_id) and linked immediately.
  3. There is no SMS code, email link, or secondary confirmation. Move directly to fetching questions or completing tests.
Do not call PUT /.../auth/verify/ when tests_auth_required is false. It returns a 400 error with the message SMS verification is not required for this organizer account.

​
Validation checks (both paths)

Regardless of the path, the API always validates:
  1. Format: name length, mobile pattern, birth date format, and boolean type.
  2. Prerequisite checks: age and gender restrictions defined by the specific test.
  3. Uniqueness: external_id must be unique within your organizer account.
If any check fails, the response returns successful: false with a descriptive message in the messages array.

​
Age and gender prerequisites

Some psychological tests restrict participation by age or gender. For example, a test may specify:
  • min_age: 18
  • max_age: 65
  • gender_permission: "male" or "female" (or null for no restriction)
If the participant does not meet these prerequisites, authentication fails with a descriptive message.

​
Auto-generated fields

After successful authentication, Braintest assigns the following fields automatically:

​
Example payload (standalone record)

​
Example payload (roadmap)

For roadmaps, provide a shared mobile and an array of role/profile pairs:
Use external_id to reliably match Braintest participants with users in your own system. It prevents duplicate profiles when the same person takes multiple tests.