Belcome API for developers
The Belcome API is the same API the Belcome Pro app uses. The owner of a business creates an API key, picks what it may do, and your code reads and writes that business's appointments, clients, menu, team and payments.
API keys
- The owner creates a key in the app, under Settings > Integrations > API keys. The key is shown once; after that Belcome shows only its name and scopes.
- Send it on every request as Authorization: Bearer <key>. A key works for one business only; another business answers 404.
- Only the owner creates, lists and revokes keys. A revoked key answers 401 from the next request on.
Base URL and responses
https://belcome.app/api/v1
Every route below is relative to the base URL. Answers come as JSON in one envelope: {"success": true, "message": ..., "data": ...}, and errors as {"success": false, "code": ..., "message": ...} with codes such as unauthenticated, forbidden_role, not_found and validation_failed.
Scopes
Reading (GET) needs the resource's read scope; writing needs its write scope. Anything not in this list stays out of reach of a key: policies, team settings, publishing and anything that charges or refunds money. Checkout, no-show fees and selling packages stay in the app.
appointments:read | Appointments, free times and calendar blocks. |
appointments:write | Book, repeat, move, resize, confirm, check in, complete, cancel or mark a no-show; block time. |
clients:read | Clients, their visit history, forms, photos and wallet balances. |
clients:write | Create, update and delete clients. |
services:read | Services, categories and locations with hours. |
staff:read | The team and each member's working hours. |
payments:read | Payments and the status of the payments account. |
Routes
Account
GET /me | The user behind the key; memberships holds only the key's business. |
GET /businesses/{business} | The business of the key (any scope). |
API keys (owner, from the app)
GET /businesses/{business}/api-keys | List keys (owner, app session only). |
POST /businesses/{business}/api-keys | Create a key; the plain key is returned once. |
DELETE /businesses/{business}/api-keys/{key} | Revoke a key. |
Appointments, availability and blocks
GET /businesses/{business}/appointments | Appointments of a location in a time window (appointments:read). |
POST /businesses/{business}/appointments | Book a visit (appointments:write). |
GET /businesses/{business}/availability | Free slots (appointments:read). |
GET /businesses/{business}/appointments/{appointment} | One appointment with its items (appointments:read). |
POST /businesses/{business}/appointments/recurring | Book the same visit every N weeks (appointments:write); body of createAppointment plus every_weeks and occurrences (1 to 52). |
PATCH /businesses/{business}/appointments/{appointment}/schedule | Move to a new start, optionally reassigning staff per item (appointments:write). 409 on a conflict unless force. |
PATCH /businesses/{business}/appointments/{appointment}/duration | Change the minutes of one item (appointments:write). |
PATCH /businesses/{business}/appointments/{appointment}/note | Write or clear the team note of the visit; the client never sees it (appointments:write). |
POST /businesses/{business}/appointments/{appointment}/transitions | Confirm, check in, complete, cancel, decline or mark a no-show (appointments:write). No fee is charged through a key. |
POST /businesses/{business}/appointments/{appointment}/forms/link | A kiosk link for the intake forms of the visit (appointments:write). |
GET /businesses/{business}/appointments/{appointment}/promotion | The promotion applied to the visit, if any (appointments:read). Applying one stays in the app. |
GET /businesses/{business}/blocks | Manual blocks on the calendar (appointments:read). |
POST /businesses/{business}/blocks | Block time for one staff member or resource (appointments:write). |
DELETE /businesses/{business}/blocks/{block} | Remove a manual block (appointments:write); with following=1, the later blocks of its repeat go too. |
Clients
GET /businesses/{business}/clients | Search clients (clients:read). |
POST /businesses/{business}/clients | Create a client (clients:write). |
GET /businesses/{business}/clients/{client} | One client (clients:read). |
PATCH /businesses/{business}/clients/{client} | Update a client; same fields as createClient (clients:write). |
DELETE /businesses/{business}/clients/{client} | Delete a client (clients:write). |
GET /businesses/{business}/clients/{client}/appointments | Visit history of the client (clients:read). |
GET /businesses/{business}/clients/{client}/photos | Photos on the client's file, newest first, with the before/after stage and the dated image-use consent; each url is signed and opens for 10 minutes (clients:read). |
GET /businesses/{business}/clients/{client}/forms | Forms the client filled in (clients:read). |
GET /businesses/{business}/clients/{client}/wallet | Packages, membership credits and gift card balances (clients:read). Selling stays in the app. |
Menu and locations
GET /businesses/{business}/services | The menu (services:read). |
GET /businesses/{business}/locations | Locations (services:read). |
GET /businesses/{business}/service-categories | Menu categories (services:read). |
GET /businesses/{business}/services/{service} | One service (services:read). |
GET /businesses/{business}/locations/{location} | One location with hours (services:read). |
Team
GET /businesses/{business}/staff | The team (staff:read). |
GET /businesses/{business}/staff/{staff}/hours | Working hours of a staff member (staff:read). |
Payments
GET /businesses/{business}/payments | Payments (payments:read). |
GET /businesses/{business}/payments/{payment} | One payment (payments:read). Refunds stay in the app. |
GET /businesses/{business}/payments/account | Status of the business payments account (payments:read). |
Webhooks
GET /businesses/{business}/webhooks | Webhook endpoints of the business (any read scope). |
POST /businesses/{business}/webhooks | REST hook subscription; each event needs the read scope of its resource. |
DELETE /businesses/{business}/webhooks/{endpoint} | Remove a webhook endpoint (any read scope). |
POST /businesses/{business}/webhooks/{endpoint}/enable | Turn a disabled endpoint back on after repeated failures (any read scope). |
Webhooks
Subscribe a URL to the events you need with POST /businesses/{business}/webhooks. Each event needs the read scope of its resource. Belcome signs every delivery with the Belcome-Signature header (t=<unix time>,v1=<HMAC-SHA256 of "t.body" with the endpoint secret>) and accepts five minutes of clock difference. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours; an endpoint that keeps failing for 3 days is turned off and the owner gets an e-mail.
Events
appointment.createdappointment.updatedappointment.canceledappointment.checked_inappointment.completedappointment.no_showclient.createdclient.updatedpayment.succeededpayment.refundedsale.completed
In med spa, wellness and skincare businesses, webhooks and Zapier carry only ids and times; read the details through the API with the key.
Zapier and Make
Belcome's own Zapier and Make apps run on these same keys and webhooks and are not in their directories yet. Until they are, Webhooks by Zapier and Make's HTTP module work today: send the key in the Authorization header and subscribe the hook URL Zapier or Make gives you.
OpenAPI file
Everything on this page, in OpenAPI 3.1, for code generators and API tools: openapi.yaml
Questions about the API: info@designmastersolutions.com or WhatsApp +1 (617) 275-3254.