SHEET 04 · INTERFACE SPECIFICATION
Everything the screen can do, the API can do.
The EveryonePlans interface is a client of this API, not a privileged layer above it. That is the whole reason you can keep your own front end: there is no capability reachable through the screen that is unreachable through the wire.
The reference implementation is bringthefront.com — a production site built entirely on this API, whose front end you can read and copy. Start there if you would rather see the calls in place than in a specification.
Diagram: a website you already own sends leads into EveryonePlans. Inside, four modules — people, schedule, tasks and money — publish to a shared event bus, which drives rules and automations. Everything the system can do is available back out over an API and webhooks, including to the site it came from.
PL-06 · TO BE SUPPLIEDSTILL · 21:9
The API, drawn
An ultra-wide banner, 21:9, drawn as a dark engineering sheet. A single horizontal cyan hairline runs the full width; hanging off it at intervals are small labelled boxes reading GET, POST, WEBHOOK, TOKEN, drawn as 1px outlined rectangles with monospace uppercase labels. Small amber tick marks punctuate the line at irregular intervals like an instrument readout. Mostly empty space — the composition should read as a measured rule, not as a busy diagram. Faint graph-paper grid. Flat 2D, no perspective, no glow. Palette: ink #070b14 background, hairline #35507d, draft cyan #4cc2ff, signal amber #ffb020, near-white #eef4ff. No rounded glassmorphic cards, no purple/pink gradients, no stock-photo people, no lens flare, no 3D chrome, no clip-art icons.
DROP AT
/art/api-band.pngFIG. 08THE CONTRACT
Ten things you can hold us to.
None of these are roadmap. Every row below is how the API behaves today.
API contract guarantees
- One response envelopeEvery success returns { data, meta }. Every failure returns { error: { code, message, details } }. You write one response handler, not one per endpoint.
- A closed error-code setError codes are a fixed, documented vocabulary — not prose that changes when somebody edits a string. Branch on the code; the message is for humans.
- Cursor paginationLists page by opaque cursor rather than by offset, so a record inserted mid-walk cannot make you skip or repeat a row.
- Idempotency keysSend Idempotency-Key on a write and a retry after a dropped connection replays the original result instead of creating a second record. The internet drops connections; billing twice is not an acceptable consequence.
- Rate limits you can seeLimits are returned in response headers, so a client can back off before it is throttled rather than after.
- Signed webhooks, with retriesEvery delivery is HMAC-signed with a timestamp so you can verify it came from us and reject replays. Failed deliveries retry on a backoff; an endpoint that fails persistently is disabled and you are told.
- A sandbox that is not productionTest mode is a separate data space with its own credentials. Nothing you do while building can touch a real customer, a real invoice or a real email.
- It evolves without breaking under youNew capabilities and fields ship additively — existing ones do not change meaning or disappear. When something genuinely has to break, it ships as a new dated version and the one you built against keeps working, so upgrading is a decision you make rather than a deadline we set.
- Scoped tokensOAuth client-credentials with per-scope grants. A token for reading the schedule cannot write an invoice.
- Strong client auth availableBeyond a client secret, the API supports private_key_jwt and DPoP-bound tokens for integrations that need a stolen token to be useless on its own.
FIG. 09AUTHENTICATION
Machine auth, scoped.
Integrations authenticate with the OAuth client-credentials grant and receive a short-lived bearer token carrying only the scopes you were granted. Rotate a secret without downtime; revoke a client without touching the others.
For integrations where a leaked bearer token would be serious, the token endpoint also accepts private_key_jwt and can issue DPoP-bound tokens — so a token lifted off the wire is useless without the key that proves possession.
$ curl -s https://api.everyoneplans.com/api/v1/oauth/token \ -d grant_type=client_credentials \ -d scope="crm.read schedule.write" \ -u "$CLIENT_ID:$CLIENT_SECRET" { "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "expires_in": 3600, "scope": "crm.read schedule.write" }
FIG. 10WEBHOOKS
Changes come to you.
Subscribe an endpoint to the event types you care about and the platform posts them as they happen. Every delivery carries a timestamp and an HMAC signature over the raw body — verify both, and reject anything older than your tolerance window, and a replayed delivery cannot be used against you.
Deliveries retry on a backoff. An endpoint that keeps failing is disabled rather than retried forever, and that is surfaced rather than silent — a webhook that stopped arriving three weeks ago is a worse outage than one that fails loudly.
X-EP-Timestamp: 1787328131 X-EP-Signature: sha256=4f2b9c8a... { "type": "lead.created", "id": "evt_01J8ZQ4M7XK2", "data": { "id": "lead_01J8ZQ4M7XK2", "email": "sam@example.com" } } <- 200 within 5s, or we retry
FIG. 11A REAL REQUEST
And what comes back.
Every response carries the same envelope, every error comes from a closed set of codes, every list is cursor-paginated, and every write accepts an idempotency key so a retry after a dropped connection cannot bill twice. The API keeps growing — but additively: when something genuinely has to break it ships as a new dated version, and the one you built against goes on working.
$ curl -X POST https://api.everyoneplans.com/api/v1/crm/leads \ -H 'Authorization: Bearer $TOKEN' \ -H 'Idempotency-Key: 8f1c-4a2e' \ -d '{"email":"sam@example.com","source":"website"}' < HTTP/1.1 201 Created { "data": { "id": "lead_01J8ZQ4M7XK2", "status": "new", "createdAt": "2026-08-20T14:02:11Z" }, "meta": { "requestId": "req_7f2a91c4" } } -> webhook lead.created dispatched to 1 endpoint
CURRENT STATE · READ THIS BIT
Credentials are issued by us, for now.
There is no self-serve developer dashboard yet. Today you tell us what you are building and we set up a client and a sandbox — usually same day.
Self-serve registration, a request log and a webhook delivery console with replay are being built, and they are the next things we ship. We would rather tell you that here than let you find it out after signing up. If a self-serve developer portal is a hard requirement for you today, say so in your first message and we will tell you honestly where it stands.