Assessment API (`/api/v1`)

Synchronous psychometric schema, submit, and results for your organisation.

Use this when your product hosts the Yareta Assessment and you want scores in Yareta (and optionally CRM). This is not GraphQL and not the Zapier key. Keys are issued per organisation and shown once.

Participants can still use invite links in the app with no API. The API is for your UI or ATS.

Base: https://platform.yareta.ai
Auth: x-api-key: <developer key>
Runtime: HTTPS JSON

GET /api/v1/assessment/questions

Returns the current instrument definition (versioned).

Useful fields in the payload:

• version (currently "1.0")
• organizationId
• scaleDescription / scaleOptions — psychometric items are integers 1–6
• totalQuestions — 140 including demographics and closing
• categories.demographics — includes required full name (q1) and email (q4)
• categories.psychometric — q5–q131 (127 items), all required to score
• categories.closing — q132–q140 optional context

Use this response to render your own UI. Do not hard-code question text; it can be updated.

POST /api/v1/assessment/submit

Submit answers for a participant.

Body (JSON):

Field	Required	Notes
email	Yes	Valid email; identifies the result
full_name	Yes	Display name
q5 … q131	Yes	Integers 1–6
benchmark_tag_id	No	Industry benchmark from the tags endpoint
Other q*	No	Demographics / closing

On success you receive { success, responseId, scores, benchmarkApplied } (field names as returned). Scoring is synchronous. One stored result per organisation + email (later submits upsert). CRM sync, if configured, runs asynchronously after save.

GET /api/v1/assessment/results

Query parameters (at least one required):

• email
• result_id

Returns the stored scored result for your organisation.

GET /api/v1/benchmark-tags

Paginated industry benchmark tags.

• page, limit (limit capped at 100)

Response includes { success, pagination, count, … }.

Example

curl -sS https://platform.yareta.ai/api/v1/assessment/questions \
  -H "x-api-key: $YARETA_KEY"

curl -sS https://platform.yareta.ai/api/v1/assessment/submit \
  -H "x-api-key: $YARETA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "full_name": "Ada Lovelace",
    "q5": 5,
    "q6": 4
  }'

(Include every required psychometric key q5–q131 in production.)

Errors

HTTP	error	Typical cause
401	Unauthorized	Missing/invalid key
400	Bad Request	Invalid JSON, bad email, missing/invalid answers (missingCount / invalidCount may be present)
500	Internal Server Error	Retry with backoff; contact support if persistent

Webhooks (developer)

You can register HTTPS endpoints to receive assessment-related events (signing secret shown once). Contact Yareta if webhook registration is not visible in your workspace yet.