Documentation · Integrations and agents
API reference
Every route, field and webhook event a church key can use, with how to check a webhook signature. Written from the OpenAPI file.
For: AdminOwner
For what keys and webhooks are and how to make them, see API keys and webhooks. The machine-readable file is at /docs/api/openapi.json.
Calling the API
Every route below starts with /api/v1. Send the key as Authorization: Bearer eos_key_…. A key may make 60 requests a minute; past that the answer is 429. A missing or ended key gets 401, and a route outside the key's scopes gets 403. Errors are JSON with a message.
Lists come newest first, 50 rows by default and at most 100 (limit). Pass since (an ISO 8601 time) to get only rows after it. Each shape named below, like IntegrationPerson, is listed under Fields.
Routes
GET /integration
The church and key this is (any key). Scope: any.
Answers 200 with IntegrationMe.
Errors: 401, 403, 429.
GET /integration/people
People who said the team may contact them, newest first. Never anyone who may be under 18. Scope: people:read.
| Send | In | Type | Notes |
|---|---|---|---|
since |
query | string (date-time) | Only rows after this moment. |
limit |
query | integer | Up to 100. |
Answers 200 with IntegrationPeople.
Errors: 401, 403, 429.
POST /integration/people
Add a person (matched by email; nobody is contacted). Scope: people:write.
| Send | In | Type | Notes |
|---|---|---|---|
first_name |
body | string | Required. |
last_name |
body | string or null | |
email |
body | string or null (email) | |
phone |
body | string or null | |
source |
body | string or null | A source's name or code. |
Answers 201 with IntegrationPersonEnvelope.
Errors: 401, 403, 422, 429.
GET /integration/people/{person}
One person, with their stages when the key has stages:read. Scope: people:read.
| Send | In | Type | Notes |
|---|---|---|---|
person |
path | integer | Required. |
Answers 200 with IntegrationPersonEnvelope.
Errors: 401, 403, 404, 429.
POST /integration/people/{person}/timeline
Add one plain line to their timeline. Scope: people:write.
| Send | In | Type | Notes |
|---|---|---|---|
person |
path | integer | Required. |
title |
body | string | Required. |
type |
body | string | One of note, milestone, pathway, serving. |
on |
body | string (date) |
Answers 201 with IntegrationTimelineEnvelope.
Errors: 401, 403, 404, 422, 429.
POST /integration/people/{person}/stage-suggestions
Suggest a stage move; staff confirm it on the person's page. Scope: stages:suggest.
| Send | In | Type | Notes |
|---|---|---|---|
person |
path | integer | Required. |
stage |
body | string | Required. A stage key or title. |
track |
body | string or null | A track key or title; the main track when left out. |
reason |
body | string or null |
Answers 201 with IntegrationSuggestionEnvelope.
Errors: 401, 403, 404, 422, 429.
GET /integration/tracks
The church's tracks and their stages. Scope: stages:read.
Answers 200 with IntegrationTracks.
Errors: 401, 403, 429.
GET /integration/stage-changes
Where people are now, most recent moves first. Scope: stages:read.
| Send | In | Type | Notes |
|---|---|---|---|
since |
query | string (date-time) | Only rows after this moment. |
limit |
query | integer | Up to 100. |
Answers 200 with IntegrationStageChanges.
Errors: 401, 403, 429.
GET /integration/results
Results as gift bands, newest first. Never answers, stories or notes. Scope: results:read.
| Send | In | Type | Notes |
|---|---|---|---|
since |
query | string (date-time) | Only rows after this moment. |
limit |
query | integer | Up to 100. |
Answers 200 with IntegrationResults.
Errors: 401, 403, 429.
GET /integration/sources
The church's sources and their links. Scope: sources:read.
Answers 200 with IntegrationSources.
Errors: 401, 403, 429.
GET /integration/webhooks
This key's own webhooks. Scope: webhooks:manage.
Answers 200 with IntegrationWebhooks.
Errors: 401, 403, 429.
POST /integration/webhooks
Subscribe a webhook (Zapier's REST hook). The secret is in this answer only. Scope: webhooks:manage.
| Send | In | Type | Notes |
|---|---|---|---|
url |
body | string | Required. A public https address. |
events |
body | list of string | Required. One of result.completed, person.added, person.stage_changed, person.erased. |
Answers 201 with IntegrationWebhookEnvelope.
Errors: 401, 403, 422, 429.
DELETE /integration/webhooks/{webhook}
Unsubscribe one of this key's webhooks. Scope: webhooks:manage.
| Send | In | Type | Notes |
|---|---|---|---|
webhook |
path | integer | Required. |
Answers 200 with Deleted.
Errors: 401, 403, 404, 429.
Webhooks
EmmauOS sends a POST with a JSON body to each webhook's address about 20 seconds after the event, once it has checked the person may still be shared. Answer with any 2xx within 10 seconds. Anything else is tried again for 24 hours, then the webhook pauses. Answering 410 removes the webhook, as Zapier expects.
| Header | What it holds |
|---|---|
EmmauOS-Event |
The event, such as result.completed. |
EmmauOS-Delivery |
The delivery's id. The same event retried keeps the body's id. |
EmmauOS-Signature |
t= the time in Unix seconds, v1= the hex HMAC-SHA256 of t + . + the raw body, keyed with the signing secret. |
| Event | data holds |
|---|---|
result.completed |
IntegrationResult |
person.added |
IntegrationPerson |
person.stage_changed |
IntegrationStageChange |
person.erased |
person_id only, so you can delete your copy. |
Checking a signature
Refuse a body whose time is more than five minutes old, and compare in constant time.
const crypto = require('crypto');
function fromEmmauOS(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}
parse_str(str_replace(',', '&', $header), $parts);
$fresh = abs(time() - (int) $parts['t']) <= 300;
$ok = $fresh && hash_equals(hash_hmac('sha256', $parts['t'].'.'.$rawBody, $secret), $parts['v1'] ?? '');
Fields
IntegrationPerson
| Field | Type | Notes |
|---|---|---|
id |
integer | |
first_name |
string | |
last_name |
string | |
email |
string or null | |
source |
string or null | |
added_at |
string or null | |
stages |
list of object |
IntegrationPeople
| Field | Type | Notes |
|---|---|---|
data |
list of IntegrationPerson |
IntegrationPersonEnvelope
| Field | Type | Notes |
|---|---|---|
data |
IntegrationPerson or null |
|
existing |
boolean |
IntegrationMe
| Field | Type | Notes |
|---|---|---|
church |
object | |
key |
object |
IntegrationTimelineEnvelope
| Field | Type | Notes |
|---|---|---|
data |
IntegrationTimeline |
IntegrationTimeline
| Field | Type | Notes |
|---|---|---|
id |
integer | |
person_id |
integer | |
title |
string | |
on |
string |
IntegrationSuggestionEnvelope
| Field | Type | Notes |
|---|---|---|
data |
IntegrationSuggestion |
IntegrationSuggestion
| Field | Type | Notes |
|---|---|---|
id |
integer | |
person_id |
integer | |
track |
string | |
stage |
string | |
status |
string |
IntegrationResult
| Field | Type | Notes |
|---|---|---|
id |
integer | |
person_id |
integer or null | |
first_name |
string | |
last_name |
string | |
email |
string or null | |
assessment |
string | |
completed_at |
string or null | |
lead_gifts |
list of string | The lead band, in the assessment's order: never a ranking. |
at_the_edge |
string or null | |
ephesians_4_leaning |
list of string |
IntegrationResults
| Field | Type | Notes |
|---|---|---|
data |
list of IntegrationResult |
IntegrationTracks
| Field | Type | Notes |
|---|---|---|
data |
list of IntegrationTrack |
IntegrationTrack
| Field | Type | Notes |
|---|---|---|
key |
string | |
title |
string | |
stages |
list of object |
IntegrationStageChange
| Field | Type | Notes |
|---|---|---|
person_id |
integer | |
track |
string | |
track_title |
string | |
stage |
string or null | |
stage_title |
string or null | |
from_stage |
string or null | |
changed_at |
string |
IntegrationStageChanges
| Field | Type | Notes |
|---|---|---|
data |
list of IntegrationStageChange |
IntegrationSources
| Field | Type | Notes |
|---|---|---|
data |
list of IntegrationSource |
IntegrationSource
| Field | Type | Notes |
|---|---|---|
id |
integer | |
name |
string | |
kind |
string | |
code |
string | |
link |
string |
IntegrationWebhook
| Field | Type | Notes |
|---|---|---|
id |
integer | |
url |
string | |
events |
list of string | |
status |
string | |
created_at |
string or null | |
secret |
string |
IntegrationWebhooks
| Field | Type | Notes |
|---|---|---|
data |
list of IntegrationWebhook |
IntegrationWebhookEnvelope
| Field | Type | Notes |
|---|---|---|
data |
IntegrationWebhook |
Deleted
| Field | Type | Notes |
|---|---|---|
deleted |
boolean |
WebhookEvent
The body of every webhook, signed in the EmmauOS-Signature header (t=
| Field | Type | Notes |
|---|---|---|
id |
string | |
event |
string | One of result.completed, person.added, person.stage_changed, person.erased. |
created_at |
string | |
church |
string | |
data |
IntegrationResult or IntegrationPerson or IntegrationStageChange or object |
Try it on your own church
Your assessment link works the minute you sign up. The first 50 people are free, and there is no card to enter.
This page as Markdown, for notes or an AI assistant.