> 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.

# Send your first record

> Create a test key, declare a definition and validate an assessment record.

This example uses an assessment because `formation.assessment_result` is the [only supported record type](/api/v1/record-types) today. The key, record envelope, receipt and delivery steps also apply when version 1 adds more types.

## 1. Create a test key

In Ediphai Console, open **Settings → Integrations → Custom apps**, add your app and copy the test key when it appears. Store it on your server as `EDIPHAI_API_KEY`. The key is shown once and selects the church, app and environment; none of those belongs in the request body. Never put the key in a browser, mobile bundle or source file.

Use `https://apps.ediphai.com` as the base URL for test and live requests. API paths already start with `/v1`.

## 2. Declare a definition

`PUT /v1/definitions/{key}/versions/{version}` must succeed before a record can use that definition. For an assessment, declare its sections, items, value types and scales. The version label belongs to your app; a live version becomes immutable once a live record refers to it. Unknown fields are refused. See the [definition schema](https://apps.ediphai.com/v1/schemas/Definition.json).

This minimal example has one section and one score. Replace its keys and scale with values from your assessment:

```sh
curl --fail-with-body -X PUT \
  'https://apps.ediphai.com/v1/definitions/serving_interests/versions/v1' \
  -H "Authorization: Bearer $EDIPHAI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "kind": "assessment",
    "name": "Serving interests",
    "roles": [{"key": "respondent", "min": 1, "max": 1}],
    "sections": [{"key": "interests", "label": "Interests", "order": 1}],
    "items": [{"key": "community", "section": "interests", "label": "Interest in community service", "value_type": "score", "scale": {"min": 0, "max": 5}}]
  }'
```

See [assessment results](/api/v1/assessment-integration) for item mapping and version rules.

## 3. Validate a record

Use the exact type and version from [supported record types](/api/v1/record-types). The example's `record_id` is the app's stable completion ID; `revision` starts at 1. `occurred_at` is the completion time, and each result must match the definition. `subjects[].external_id` is the person's ID in your app. If you know their ID in a church people system, add `claims.source_refs`; see [people and identity](/api/v1/people-and-identity).

With a test key, `?validate=true` checks the request without storing it. Expect HTTP 200 with `outcome: "valid"`:

```sh
curl --fail-with-body -X POST \
  'https://apps.ediphai.com/v1/records?validate=true' \
  -H "Authorization: Bearer $EDIPHAI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "record_type": "formation.assessment_result",
    "record_type_version": 1,
    "record_id": "completion_123",
    "revision": 1,
    "occurred_at": "2026-10-20T14:00:00Z",
    "subjects": [{"role": "respondent", "external_id": "person_123", "claims": {"first_name": "Avery", "last_name": "Example"}}],
    "body": {
      "definition": {"key": "serving_interests", "version": "v1"},
      "status": "completed",
      "completed_at": "2026-10-20T14:00:00Z",
      "results": [{"item": "community", "value": 4}]
    }
  }'
```

## 4. Store and check the receipt

Remove `?validate=true` to store the record. Before sending, persist the request and its stable `record_id` and `revision` in a durable [outbox](/api/v1/delivery-and-retries). Expect HTTP 202 with `outcome: "accepted"`; an identical retry returns HTTP 200 with `outcome: "duplicate"`. Save the receipt, then use status or reconciliation to check later progress. `accepted` says the API took responsibility for the record. It does not prove a person link or a queryable result.

Run the [sender self-test](/api/v1/self-test) before using a separate live key and outbox. Test records never enter the church's data; a test receipt cannot stand in for a live send.