Developer documentation

The Comflyant API

Scheduled, SMS-delivered forms for UK healthcare — recipients, versioned templates, plans and schedules, forms and webhooks, over one compliant, UK-resident API. Everything the dashboard does, your product can do too.

Open the API reference

Quickstart

Every request is authenticated with your organization's API key and runs over HTTPS. Here's the shortest path from zero to a successful call.

1. Get an API key

API keys are issued per organization. Create one from the Comflyant dashboard (Settings → API keys), or — if you already hold a key — mint more from the API itself via POST /v1/organization/api-keys. The raw key is shown once, at creation; store it somewhere safe and treat it like a password. Keys can be revoked at any time and never expire unless you set an expiry.

By default a key is an org / service credential — its requests are audited as the integration itself. To attribute API actions to an individual, create a staff user with POST /v1/users and pass its user_id when you mint the key: that key is user-scoped, so everything it does is logged against that person. API-provisioned users are API-only (no dashboard sign-in, no MFA) until you invite them.

2. Base URL

All developer endpoints live under the /v1 prefix:

https://api.comflyant.co.uk/v1

3. Make your first authenticated call

Send your key in the X-API-Key header. This returns the organization that owns the key — a good first request to confirm your credentials work:

curl https://api.comflyant.co.uk/v1/organization \
  -H "X-API-Key: $COMFLYANT_API_KEY"

A successful response looks like:

{
  "id": "0b3a7f7e-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
  "name": "Riverside Health",
  "contact_email": "ops@riverside.example",
  "status": "active",
  "created_at": "2026-10-01T09:30:00Z"
}

A missing or invalid key returns 401 Unauthorized. Keep your key server-side — never ship it in a browser or mobile app.

4. Where to go next

Explore every endpoint, with request/response schemas and runnable examples, in the interactive API reference.

Authentication

Developer (/v1) endpoints authenticate with an API key in the X-API-Key request header:

X-API-Key: your-api-key

The key resolves to exactly one organization, and that organization scopes every resource you can read or write — there is no cross-tenant access. Store keys only as a server-side secret. They are kept as a hash (never in plaintext), can carry an optional expiry, and are revocable immediately.

The Comflyant dashboard (the /app endpoints) uses short-lived user JWTs (Authorization: Bearer …) instead — that surface backs our own web app. If you're building an integration, target /v1 with an API key.

The resource model

A quick tour of the objects you'll work with. See the reference for the full field-by-field schema of each.

Organization: Your tenant. The organization owning the API key is resolved on every request; everything else is scoped to it. Manage your organization and its API keys under /v1/organization.
Recipients: The people who receive your messages — name, UK phone number (E.164) and timezone, plus an optional external_ref to tie back to your own records. A durable signed link token is minted per recipient.
Form templates & versions: A form template is the logical lineage (name, description); each version owns the questions and a status (draft / published / archived). Structural edits create a new version — forms already sent never change.
Informational templates: One-way messages that are just sent, with no response expected — the counterpart to forms within a plan.
Plans & schedules: A plan is what a recipient is enrolled on; it is made of deliverables (forms or informationals). Plan templates are the reusable library; a recipient plan is an enrollment. Schedules are the execution unit the cron dispatches.
Forms: A form instance sent to a recipient. It snapshots its template version's questions at creation and records the answers as they come back. One-off sends are ad-hoc forms with no schedule.
Messages: The outbound SMS log — purpose, delivery status, segment count and the provider's message id — so you can audit exactly what was sent and what happened to it.
Webhooks: Register HTTPS endpoints to receive events as they happen. Each delivery is signed so you can verify it came from Comflyant, and failed deliveries are retried.
Staff users & audit attribution: Provision your own staff via /v1/users and give each a user-scoped API key, so every request is attributed to a named person in the audit log. API-provisioned users are API-only (no dashboard login, no MFA) until you invite them to the dashboard.

Data residency

All data and infrastructure are hosted in the United Kingdom (London, europe-west2). Comflyant is the data processor; your organization is the data controller. See our trust & security page for the controls in place.

Versioning & stability

The /v1 resource API follows semantic versioning, surfaced as info.version in the OpenAPI spec. Build against it with confidence:

Additive changes ship in minor releases. We may add new endpoints, new optional fields, and new enum values without a version bump — so write clients that ignore unknown fields rather than reject them.
We won't break you within a major version. We don't remove or rename a field, tighten a type, or change the meaning of an existing response on /v1 without incrementing the major version.
Breaking changes get a new major version and a deprecation window, so you have time to migrate before the old version is retired.

These promises are enforced in our CI: a backward-incompatible change to a published /v1 shape fails the build unless it is shipped as a new major version.

Ready to dig in? Open the interactive API reference to browse every endpoint and try requests against your own key.