All pages

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=,v1=<hex HMAC-SHA256 of ".">).

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.

Start your church free Take the assessment

This page as Markdown, for notes or an AI assistant.