Send your first record

This example uses an assessment because formation.assessment_result is the only supported record type 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.

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

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 for item mapping and version rules.

3. Validate a record

Use the exact type and version from supported 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.

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

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