Skip to navigation
APIBuild an integration

People and identity

Every record has a subjects array. Give each person a stable external_id from your app; use the same ID for that person across all record types sent by that app. The definition declares the allowed subject roles. An assessment uses one respondent. The paths below refer to fields inside each subject.

Subject fields

subjects[].role
string

A role declared by this record’s definition; respondent for an assessment.

subjects[].external_id
string

Your app’s stable person ID, not the ID in CCB, Planning Center or another people system.

subjects[].claims.source_refs
array of objects

Add a system, id and basis when your app knows a church people-system ID. The system must be referenceable for this church.

subjects[].claims.first_name
string

The person’s first name as your app holds it.

subjects[].claims.last_name
string

The person’s last name as your app holds it. A name alone cannot establish an automatic link.

subjects[].claims.date_of_birth
date

Send the full birth date only when your app knows it. Do not invent a day.

subjects[].claims.birth_year
integer

Use this when you know only the year; do not send it with subjects[].claims.date_of_birth.

subjects[].claims.email
string

An email address your app actually holds.

subjects[].claims.phone_e164
string

A phone number your app actually holds in E.164 format.

subjects[].claims.phone_verified
boolean

Set this to true only when your app verified control of that number.

For example, when staff entered a CCB ID into the app:

{
  "subjects": [{
    "role": "respondent",
    "external_id": "person_123",
    "claims": {
      "first_name": "Avery",
      "last_name": "Example",
      "source_refs": [{"system": "ccb", "id": "48213", "basis": "staff_entered"}]
    }
  }]
}

Use lookup_confirmed only after an actual lookup, staff_assigned when staff invited or assigned the person from that system, and self_reported when the person supplied the ID. A stored ID with unknown provenance does not become lookup_confirmed merely because it was saved.

Ediphai checks a source reference against the other claims; a reference does not force a contradictory match. Without one, send the name and any other real facts the app has. Ediphai may attach the record or hold it for church review. The receipt never reveals the link decision, so do not wait for a birth date or guess one before sending.

For an assessment completed by a child on a parent’s account, the child is the respondent. Add the parent as guardian only if the definition declares that role. Do not put the child’s answers on the parent to make a match pass.