{"openapi":"3.1.0","info":{"title":"Scoring Engine API","version":"2.0","description":"Data-only scoring API (no report generation). Synchronous scoring with optional HMAC-signed webhooks. Scoring scopes are requestable \u00e0 la carte; every scored result records the norm set used. Data retention: assessments and their results are kept until you erase the person with `DELETE /v2/assessments/{id}/pii` (the results stay, anonymized); `Idempotency-Key` replays are kept 24 hours; webhook delivery records 30 days after delivery or 90 days after a final failure."},"servers":[{"url":"/"}],"security":[{"bearerAuth":[]}],"paths":{"/v2/assessments":{"post":{"summary":"Create an assessment from registration info","operationId":"createAssessment","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["firstname","lastname","email","language"],"properties":{"firstname":{"type":"string"},"middlename":{"type":["string","null"]},"lastname":{"type":"string"},"email":{"type":"string","format":"email"},"language":{"type":"string","enum":["en","fr","pt"]},"gender":{"type":["string","null"],"enum":["M","F","X",null],"description":"Optional. M or F selects the matching norm set for scopes that use norms. X or omitted means unspecified: the engine scores on its general norm set and flags the result `provisional`. Ignored by scopes that do not use norms."},"dob":{"type":["string","null"],"format":"date","description":"Never used in scoring."},"external_id":{"type":["string","null"],"description":"Your own reference for this person or order (e.g. an order id), echoed on every response and webhook."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentStatus"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/assessments/{id}/tools/{tool}":{"put":{"summary":"Submit or replace one tool's responses (validated on write)","operationId":"submitTool","parameters":[{"$ref":"#/components/parameters/AssessmentId"},{"name":"tool","in":"path","required":true,"schema":{"type":"string","enum":["reflections","personalmotivators","areamissions","abilitiesfilter","personalstyle","personalexpectations","person","role","organization","demographics","demographics"]}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["responses"],"properties":{"responses":{"description":"Either a {q: a} map or a list of {q, a} items; q is 1-based.","oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","required":["q","a"],"properties":{"q":{"type":"integer"},"a":[]}}}]}}}}}},"responses":{"200":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentStatus"}}}},"422":{"description":"Structured per-item validation errors {tool, q, rule, expected, got}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/assessments/{id}/score":{"post":{"summary":"Score the assessment for the requested scopes (synchronous)","operationId":"scoreAssessment","parameters":[{"$ref":"#/components/parameters/AssessmentId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"string","enum":["mcs.m","mcs.c","mcs.s","mcs","pro.person","pro.role","pro.org","insights","reflections","full"]},"default":["full"]},"format":{"type":"string","enum":["keys","strings"],"default":"keys"},"language":{"type":"string","enum":["en","fr","pt"],"description":"Content language for strings format; defaults to the registration language."},"norms":{"type":"string","description":"Optional override: male | female | pooled | <norm_set_id>. Defaults from the registrant's gender; unspecified-gender registrants are scored on the general set automatically. Named sets are listed at /v2/reference/norm-sets."},"access_code":{"type":"string","description":"Required on every scoring call: the access code names the order being scored (its product, allowed scopes, order type and payouts). Requested scopes must be within the code's allowance."},"audit":{"type":"boolean","default":false,"description":"Capture the explainability trace, retrievable at /v2/assessments/{id}/results/audit."}}}}}},"responses":{"200":{"description":"Scored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultEnvelope"}}}},"403":{"description":"Access-code problem (unknown, unusable, or scopes outside its allowance)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Missing tools per scope, unknown scope, or norm-set problem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/score":{"post":{"summary":"One-shot: registration + tools + scoring in a single call","operationId":"scoreOneShot","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["registration","tools"],"properties":{"registration":{"type":"object","required":["firstname","lastname","email","language"],"properties":{"firstname":{"type":"string"},"middlename":{"type":["string","null"]},"lastname":{"type":"string"},"email":{"type":"string","format":"email"},"language":{"type":"string","enum":["en","fr","pt"]},"gender":{"type":["string","null"],"enum":["M","F","X",null],"description":"Optional. M or F selects the matching norm set for scopes that use norms. X or omitted means unspecified: the engine scores on its general norm set and flags the result `provisional`. Ignored by scopes that do not use norms."},"dob":{"type":["string","null"],"format":"date","description":"Never used in scoring."},"external_id":{"type":["string","null"],"description":"Your own reference for this person or order (e.g. an order id), echoed on every response and webhook."}}},"tools":{"type":"object","description":"Map of tool name to responses ({q: a} map or [{q, a}] list).","additionalProperties":true},"scopes":{"type":"array","items":{"type":"string","enum":["mcs.m","mcs.c","mcs.s","mcs","pro.person","pro.role","pro.org","insights","reflections","full"]},"default":["full"]},"format":{"type":"string","enum":["keys","strings"],"default":"keys"},"language":{"type":"string","enum":["en","fr","pt"],"description":"Content language for strings format; defaults to the registration language."},"norms":{"type":"string","description":"Optional override: male | female | pooled | <norm_set_id>. Defaults from the registrant's gender; unspecified-gender registrants are scored on the general set automatically. Named sets are listed at /v2/reference/norm-sets."},"access_code":{"type":"string","description":"Required on every scoring call: the access code names the order being scored (its product, allowed scopes, order type and payouts). Requested scopes must be within the code's allowance."},"audit":{"type":"boolean","default":false,"description":"Capture the explainability trace, retrievable at /v2/assessments/{id}/results/audit."}}}}}},"responses":{"201":{"description":"Created and scored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultEnvelope"}}}},"403":{"description":"Access-code problem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation or scope problem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/assessments/{id}":{"get":{"summary":"Status: tools received, per-scope readiness, results available","operationId":"getAssessment","parameters":[{"$ref":"#/components/parameters/AssessmentId"}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentStatus"}}}}}}},"/v2/assessments/{id}/results":{"get":{"summary":"Re-render the latest result (any scope subset, format, language, any time; text pinned to the release it was scored under)","operationId":"getResults","parameters":[{"$ref":"#/components/parameters/AssessmentId"},{"name":"scope","in":"query","schema":{"type":"string"},"description":"Comma-separated subset of the scored scopes."},{"name":"format","in":"query","schema":{"type":"string","enum":["keys","strings"],"default":"keys"}},{"name":"language","in":"query","schema":{"type":"string","enum":["en","fr","pt"]}},{"name":"content","in":"query","schema":{"type":"string","enum":["pinned","latest"],"default":"pinned"},"description":"pinned: strings from the content release the result was scored under (a report never changes unless asked). latest: the current release."},{"name":"content_release","in":"query","schema":{"type":"integer"},"description":"Strings from this specific content release (see /v2/reference/content-releases). Overrides `content`."}],"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultEnvelope"}}}},"404":{"description":"Not scored yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/assessments/{id}/results/audit":{"get":{"summary":"Explainability trace: rules fired, stage values, content keys (score with audit:true)","operationId":"getAudit","parameters":[{"$ref":"#/components/parameters/AssessmentId"}],"responses":{"200":{"description":"Audit trace"},"404":{"description":"Not scored, or scored without audit:true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/assessments/{id}/pii":{"delete":{"summary":"Erase the person from an assessment, keeping its results","description":"Clears firstname, middlename, lastname, email, dob and external_id and stamps `anonymized_at`. Tools, results and usage records stay, so `GET /v2/assessments/{id}/results` keeps working (with `external_id: null`). Use it for a data-subject erasure request. Idempotent: a repeat returns the same `anonymized_at`. Copies of `external_id` inside stored idempotency replays and webhook delivery records age out under their own retention windows. The data is not recoverable afterwards.","operationId":"anonymizeAssessment","parameters":[{"$ref":"#/components/parameters/AssessmentId"}],"responses":{"200":{"description":"Anonymized; the status body with `anonymized_at` set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentStatus"}}}},"404":{"description":"Not found (or not created by this key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/reference/languages":{"get":{"summary":"Supported languages (code, locale, region for flags, names), content coverage and last change per language, norm status, current content release","operationId":"referenceLanguages","responses":{"200":{"description":"Languages. Poll this to learn when a language's text changed: compare content_last_changed.release_id with what you last pulled."}}}},"/v2/reference/content-releases":{"get":{"summary":"Published content release history, newest first (release_id, version, published_at, notes, content_hash, current)","operationId":"referenceContentReleases","responses":{"200":{"description":"Content releases"}}}},"/v2/reference/versions":{"get":{"summary":"Content version per tool \u00d7 language (first 16 hex of a hash over that tool's question text and respondent copy), no bodies. Compare with what you hold; re-pull a tool when its version moved. ETag / If-None-Match supported.","operationId":"referenceVersions","parameters":[{"name":"content_release","in":"query","schema":{"type":"integer"},"description":"Render from a specific content release (see /v2/reference/content-releases). Default: the current release."},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"{content: {release_id, version, published_at}, versions: {<tool|assessment|demographics>: {<language>: <16-hex>}}}"},"304":{"description":"Unchanged since the ETag you sent"}}}},"/v2/reference/questions":{"get":{"summary":"Everything to render a questionnaire: per tool its validation spec, the copy around the questions (content: title, instructions, labels, scale labels, reflection prompts\u2026) and the questions; the welcome text (assessment); the optional demographics tool with its option keys. ETag = release + selection; send If-None-Match to get a 304 when unchanged. Question count and order per tool never change \u2014 only wording does.","operationId":"referenceQuestions","parameters":[{"name":"tool","in":"query","schema":{"type":"string","enum":["reflections","personalmotivators","areamissions","abilitiesfilter","personalstyle","personalexpectations","person","role","organization","demographics","demographics"]}},{"name":"language","in":"query","schema":{"type":"string","enum":["en","fr","pt"],"default":"en"}},{"name":"product","in":"query","schema":{"type":"string","default":"VC18"},"description":"Catalog product code: which tools, and which version of each, the questionnaire covers. Default: the launch product. Unknown codes are a 404 unknown_product listing known_products."},{"name":"content_release","in":"query","schema":{"type":"integer"},"description":"Render from a specific content release (see /v2/reference/content-releases). Default: the current release."},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"{language, product, content: {release_id, version, published_at}, assessment: {title, welcome_title, welcome_body}, tools: {<tool>: {validation, content: {title, instructions | {pick, top}, group_label?, labels?, scale? {min, max, min_label, max_label}, info?, time_limit_minutes?, prompts? [{key, q_from, q_to, text}]}, questions: [{q, text}]}, demographics: {validation, optional: true, content: {title, instructions, prefer_not_to_say}, questions: [{q, key, text, options: [{key, text}]}]}}}. Only fields a tool has appear; a missing translation is omitted, never replaced with English.","headers":{"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}},"304":{"description":"Unchanged since the ETag you sent"}}}},"/v2/reference/translations":{"get":{"summary":"English-keyed key\u2192string maps for keys-mode clients. ETag = release + language; send If-None-Match to get a 304 when unchanged.","operationId":"referenceTranslations","parameters":[{"name":"language","in":"query","schema":{"type":"string","enum":["en","fr","pt"],"default":"en"}},{"name":"content_release","in":"query","schema":{"type":"integer"},"description":"Render from a specific content release (see /v2/reference/content-releases). Default: the current release."},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"archetype_details, insight_details, lookup_definitions maps plus the content block {release_id, version, published_at}","headers":{"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}},"304":{"description":"Unchanged since the ETag you sent"}}}},"/v2/reference/scopes":{"get":{"summary":"Scope catalog: required tools, norm behavior, output shape. The reflections add-on is optional: no scope lists it as required and its section echoes null for whatever was not submitted.","operationId":"referenceScopes","responses":{"200":{"description":"Scopes"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Client API key, issued in the control panel; hashed at rest. Says who is calling; the access_code on each scoring call says what is being scored."}},"parameters":{"AssessmentId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Assessment public id (ULID)."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Same key + same payload replays the stored response; same key + different payload is a 409. Keys are kept 24 hours; after that the same key is treated as a new request."},"IfNoneMatch":{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"The ETag from your last pull; a match returns 304 with no body."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}},"ResultEnvelope":{"type":"object","properties":{"assessment_id":{"type":"string"},"external_id":{"type":["string","null"]},"scored_at":{"type":"string","format":"date-time"},"language":{"type":"string"},"format":{"type":"string","enum":["keys","strings"]},"norms":{"type":"object","properties":{"set_id":{"type":"string","description":"Recorded forever on the result; 'none' when no requested scope uses norms."},"provisional":{"type":"boolean","description":"true when the norm set used is a stand-in for the registrant's population (for example an unspecified gender). The result is valid but may shift if re-scored once a dedicated set is active."}}},"rules":{"type":"object","description":"The rule set (scoring rules and matrices) the result was scored with. Recorded on the result at scoring time and listed with the norm set and content release.","properties":{"set_id":{"type":"integer"},"version":{"type":"string","description":"e.g. 2016.01.01-1 \u2014 the original Pro-D ruleset"},"published_at":{"type":["string","null"],"format":"date-time"}}},"development":{"type":"boolean","description":"Present and true when the access code is a development code: the result is real, but the call was not metered, charged, paid out or sampled into the norms, and the assessment is hidden from reports and purgeable by the panel."},"content":{"type":"object","description":"The content release the strings came from. Recorded on the result at scoring time; strings render from it by default.","properties":{"release_id":{"type":"integer"},"version":{"type":"string","description":"e.g. 2016.01.01-1"},"published_at":{"type":["string","null"],"format":"date-time"},"pinned":{"type":"boolean","description":"true when rendered from the release the result was scored under; false under content=latest or an explicit content_release that differs."}}},"scopes":{"type":"object","description":"One entry per requested scope; each scope's output shape is described at /v2/reference/scopes."}}},"AssessmentStatus":{"type":"object","properties":{"assessment_id":{"type":"string"},"external_id":{"type":["string","null"]},"language":{"type":"string"},"gender":{"type":["string","null"]},"anonymized_at":{"type":["string","null"],"format":"date-time","description":"Set once the person has been erased (DELETE /v2/assessments/{id}/pii); name, email, dob and external_id are null from then on. Results still render."},"tools":{"type":"object","description":"tool \u2192 {received, valid, submitted_at}"},"scopes_ready":{"type":"object","description":"scope \u2192 bool (all required tools submitted; reflections needs none and is always ready)"},"results":{"type":"array","items":{"type":"object"}}}}}},"webhooks":{"scored":{"post":{"summary":"Sent to the API key's webhook_url after each successful scoring call","description":"Delivered as a JSON POST, sent after the scoring response and never as part of it. Verify every delivery: read `X-Timestamp` (unix seconds) and the raw request body, compute HMAC-SHA256 over the string `\"{X-Timestamp}.{raw body}\"` with the key's webhook secret (shown once in the control panel), hex-encode, and compare to `X-Signature` in constant time. Reject deliveries whose timestamp is more than 300 seconds from now. Respond 2xx to acknowledge; anything else (or a timeout after 10s) is retried at +10s, +60s, +5m, +15m \u2014 five attempts in total. `X-Delivery-Id` is stable across retries of the same event, so idempotent receivers dedupe on it. Delivery records, payload included, are kept 30 days once delivered and 90 days after the final failed attempt, then deleted. Payload is the result envelope in `keys` format plus `event: \"scored\"`.","parameters":[{"name":"X-Event","in":"header","required":true,"schema":{"type":"string"},"description":"Event name: scored | failed"},{"name":"X-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when the delivery was signed"},{"name":"X-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"Hex HMAC-SHA256 of \"{X-Timestamp}.{raw body}\" under the key's webhook secret"},{"name":"X-Delivery-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Stable id for this event across retries"}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResultEnvelope"},{"type":"object","properties":{"event":{"type":"string","const":"scored"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges delivery"}}}},"failed":{"post":{"summary":"Sent when scoring an existing assessment fails","description":"Delivered as a JSON POST, sent after the scoring response and never as part of it. Verify every delivery: read `X-Timestamp` (unix seconds) and the raw request body, compute HMAC-SHA256 over the string `\"{X-Timestamp}.{raw body}\"` with the key's webhook secret (shown once in the control panel), hex-encode, and compare to `X-Signature` in constant time. Reject deliveries whose timestamp is more than 300 seconds from now. Respond 2xx to acknowledge; anything else (or a timeout after 10s) is retried at +10s, +60s, +5m, +15m \u2014 five attempts in total. `X-Delivery-Id` is stable across retries of the same event, so idempotent receivers dedupe on it. Delivery records, payload included, are kept 30 days once delivered and 90 days after the final failed attempt, then deleted. Fires only once an assessment exists \u2014 `POST /v2/assessments/{id}/score` failures always, `POST /v2/score` failures after tool validation has passed. Authentication, tool-validation and unknown-assessment errors are returned in the synchronous response only.","parameters":[{"name":"X-Event","in":"header","required":true,"schema":{"type":"string"},"description":"Event name: scored | failed"},{"name":"X-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when the delivery was signed"},{"name":"X-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"Hex HMAC-SHA256 of \"{X-Timestamp}.{raw body}\" under the key's webhook secret"},{"name":"X-Delivery-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Stable id for this event across retries"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["event","assessment_id","failed_at","error"],"properties":{"event":{"type":"string","const":"failed"},"assessment_id":{"type":"string"},"external_id":{"type":["string","null"]},"failed_at":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string","description":"Same error code the synchronous response carried, e.g. missing_tools, norm_set_unavailable, internal_error"},"message":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges delivery"}}}}}}