---
name: ediphai-api
description: Build and check a sender for the Ediphai record intake API. Assessment results are the first supported type.
---

# Ediphai API sender

Use the current [OpenAPI file](https://apps.ediphai.com/v1/openapi.json) and [JSON Schemas](https://apps.ediphai.com/v1/schemas/Envelope.json) as the request contract. Check [supported record types](https://docs.ediphai.com/api/v1/record-types), then read the [quickstart](https://docs.ediphai.com/api/v1/quickstart) and [delivery guide](https://docs.ediphai.com/api/v1/delivery-and-retries) before writing code.

## Build the sender

1. Store the test and live keys only in the server's secret store as `EDIPHAI_API_KEY`. The API base URL for both is `https://apps.ediphai.com`; operation paths in the OpenAPI file already start with `/v1`. The key chooses the church, app and environment. Never send the key to a browser or mobile client.
2. Use an exact supported `record_type` and `record_type_version`. Today the only accepted pair is `formation.assessment_result` and `1`; there are no short aliases. Declare its assessment definition before a record uses it. Take item meanings and scales from the church's instrument, and version the definition when they change.
3. Give each record a stable `record_id` and a positive `revision`. A retry repeats the same body and revision. A changed record gets a higher revision.
4. Include each subject's stable app `external_id` and a `claims.source_refs` entry when the app knows an ID in the church's people system. State how the ID was obtained in `basis`. For an assessment the subject role is `respondent`. If the source ID or birth date is missing, send the record with the real claims the app has; Ediphai may hold it for church review.
5. Persist the full request in a durable outbox before sending. Keep separate test and live outboxes. Mark a row delivered only after a durable receipt, and reconcile uncertain outcomes. A test receipt never means a live result was sent.
6. Ignore unknown response fields. Treat unfamiliar states and problem rules as nonterminal until checked against current docs. Retry transient failures with backoff; correct validation errors before resending.
7. Run the [eight-step sender self-test](https://docs.ediphai.com/api/v1/self-test) with a test key. Then have the church review the definition and the live-key handling before any real record is sent.

The API does not tell a sender which Ediphai person matched. Do not claim that an `accepted` receipt proves a person link or a queryable result.