# 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: Admin, Owner
Canonical: https://emmauos.com/docs/api-reference

For what keys and webhooks are and how to make them, see [API keys and webhooks](/docs/api-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](#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.

```js
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 || ''));
}
```

```php
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=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">).

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