> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ediphai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ediphai.com/_mcp/server.

# Assessment results

> Map a completed assessment to the supported formation record type.

`formation.assessment_result` version `1` is the assessment body contract. Score the assessment in your app, then send completed results from your server with `POST /v1/records`, `record_type: "formation.assessment_result"` and `record_type_version: 1`. Keep question wording and any scoring audit your app needs in its own system.

## Map a completion

**`record_id`** `string`

Use the app's stable completion ID. A retake gets a new ID.

---

**`revision`** `integer`

Start at 1 and increase it when the same completion changes.

---

**`occurred_at`** `date or timestamp`

The completion time at the precision your app actually knows.

---

**`body.completed_at`** `date or timestamp`

Use the same real completion time in the assessment body.

---

**`body.definition.key`** `string`

Identify the assessment instrument your app declared before sending the result.

---

**`body.definition.version`** `string`

Identify the assessment and scoring version used for this completion.

---

**`subjects[].external_id`** `string`

Use the respondent's stable app person ID, with a [source reference](/api/v1/people-and-identity) when known.

---

**`body.results`** `array of results`

Send the score, selection, rank or text for each reported item. Each `item` must be declared with a matching value type.

---

Persist the complete request in a durable [outbox](/api/v1/delivery-and-retries) before sending it. A receipt does not prove that Ediphai linked the person or made the result queryable.

## Definition and result rules

Before the first send, use `PUT /v1/definitions/{key}/versions/{version}`. Declare the sections and result items your app sends, including each item's value type and any scale or allowed values. The `version` identifies your instrument version, not an Ediphai release. A new scoring rule, item meaning or scale needs a new definition version once live records use the old one.

Use keys matching the [definition schema](https://apps.ediphai.com/v1/schemas/Definition.json): lower-case letters, digits and underscores, starting with a letter, up to 64 characters for each section or item key. Unknown definition fields are refused.

Send computed scores, categories, selections or text only for items the church intends Ediphai to receive. If the app has a native rank, primary marker or coverage count, preserve it in the corresponding result fields. An item never presented may use `"not_offered"`; an omitted result means the app did not report it, while `null` means it reported no value.

Confirm the church has approved any free text before sending it. Assessment results, including free text, use the current formation-data access in Ediphai and may appear in Dashboard reads and saved links.

The [record schema](https://apps.ediphai.com/v1/schemas/Envelope.json) and [assessment body schema](https://apps.ediphai.com/v1/schemas/AssessmentResultBody.json) specify the exact JSON shape. Run the [sender self-test](/api/v1/self-test) with a test key before sending live records. A test receipt validates the sender but does not place a result in the church's warehouse.