API reference: every endpoint
Every REST endpoint with its parameters, an example request and response, and the full booking and order objects.
All paths are under https://www.useordina.com/api/v1 and need Authorization: Bearer <key>. See API keys and authentication.
Webhooks, actions, intakes and knowledge are per key or app: you list, read, change and delete only your own, plus older shared webhooks, actions and knowledge. See What belongs to your key or app.
At a glance
| Method | Path | What it does |
|---|---|---|
| GET | /me | The business this key belongs to |
| GET | /appointments | Appointments, newest first |
| GET | /orders | Orders, newest first |
| GET | /webhooks | The webhook endpoints you created, and the event names |
| POST | /webhooks | Subscribe an https URL to events |
| DELETE | /webhooks/{id} | Unsubscribe |
| GET | /actions | The connected actions you registered |
| POST | /actions | Register a connected action |
| GET | /actions/{id} | One action and its recent calls |
| PATCH | /actions/{id} | Change an action |
| DELETE | /actions/{id} | Remove an action |
| GET | /intakes | The intakes you registered |
| POST | /intakes | Register an intake |
| GET | /intakes/{id} | One intake |
| PATCH | /intakes/{id} | Change an intake |
| DELETE | /intakes/{id} | Remove an intake and its responses |
| GET | /intakes/{id}/responses | Its responses, newest first |
| GET | /knowledge | Knowledge you pushed |
| PUT | /knowledge/{key} | Create or replace knowledge |
| DELETE | /knowledge/{key} | Remove knowledge |
GET /me
The business the key belongs to.
{ "id": "6f1c2a8e-...", "handle": "brightsalon", "name": "Bright Salon", "currency": "NGN", "country": "NG" }
| Field | Type | Notes |
|---|---|---|
| id | string (uuid) | Stable. Use it to key your records. |
| handle | string | The last part of the booking link, as in useordina.com/book/brightsalon |
| name | string | The business's display name |
| currency | string | ISO 4217 code for every amount this business returns |
| country | string | ISO 3166-1 alpha-2 |
GET /appointments
| Query | Default | Notes |
|---|---|---|
| limit | 25 | 1 to 100 |
| status | all | For example confirmed, completed, cancelled, no_show |
| since | none | A date, YYYY-MM-DD. Only appointments on or after it. |
GET /api/v1/appointments?status=confirmed&since=2026-10-01&limit=2
{
"data": [
{
"id": 4182,
"status": "confirmed",
"date": "2026-10-03",
"time": "14:30",
"duration_minutes": 90,
"service": { "id": "a7d0...", "name": "Knotless braids", "price": "45000" },
"addons": [],
"staff": { "name": "Bola", "requested": true },
"client": { "name": "Ada Obi", "email": "ada@example.com", "phone": "+2348012345678" },
"payment": { "status": "paid", "amount_paid": 45000, "agreed_amount": null, "pay_mode": "online", "fee_amount": null, "balance_due": null, "balance_paid_at": null, "currency": "NGN", "reference": "ord_..." },
"location": null,
"notes": "First visit",
"reschedule_count": 0,
"original_date": null,
"original_time": null,
"links": {
"reschedule": "https://www.useordina.com/reschedule/...",
"cancel": "https://www.useordina.com/appointments/cancel/..."
},
"conversation_id": "c0a9...",
"created_at": "2026-09-30T18:02:11.000Z"
}
]
}
The booking object
| Field | Type | Notes |
|---|---|---|
| id | number | |
| status | string | confirmed, completed, cancelled, no_show and similar |
| date, time | string | In the business's time zone |
| duration_minutes | number | The whole visit, add-ons included |
| service | object | id, name, price (the listed price today, as the business wrote it) |
| addons | array | The add-ons booked with the service, in order, as the customer saw them: [{ "name": "Deep conditioning", "price": 5000, "minutes": 20 }]. price 0 is a free add-on; minutes is the time it adds. An empty array when there are none. With add-ons, payment.agreed_amount is the whole price, service and add-ons together (null only when that equals the listed price, as with free add-ons) |
| staff | object or null | Who the booking is with: { "name": "Bola", "requested": true }. name is the name customers see (null when the business has not set one for that person); requested is true when the customer asked for that person, false when the booking was made for anyone available and given to them. Null when nobody is assigned, including every business that does not use team calendars |
| party_size | number | How many people the booking is for. Present only when the service asks how many people; a booking of any other service has no party_size key at all |
| table | object or null | The table the party is seated at: { "label": "T3" } (the label null when the business left it empty). Null when the booking holds no table. Present only with party_size |
| client | object | name, email, phone (any can be null) |
| payment | object | status, amount_paid, agreed_amount (the price the booking was sold at, after a negotiation or a sale; null when it was the listed price), pay_mode, fee_amount, balance_due, balance_paid_at, currency, reference. See How a booking is paid, below |
| location | string or null | A meeting link, or the client's address for a home visit |
| notes | string or null | |
| reschedule_count, original_date, original_time | Set once a booking has moved | |
| links | object or null | The client's own reschedule and cancel pages |
| conversation_id | string or null | The Secretary conversation the booking came from |
| created_at | string |
How a booking is paid
| Field | Type | Notes |
|---|---|---|
| pay_mode | string or null | "online" (paid in full online), "venue" (paid at the visit) or "fee" (a booking fee online, the rest at the visit). Null on bookings made before 24 October 2026 |
| fee_amount | number or null | The booking fee charged online, before any processing fee. Set only when pay_mode is "fee" |
| balance_due | number or null | What is left to pay at the visit: the price the booking was sold at, minus the fee. Set only when pay_mode is "fee" |
| balance_paid_at | string or null | When the balance was marked collected, by completing the booking or by the owner's "Mark balance collected". Null while it is due |
With a booking fee, amount_paid is what was paid online (the fee and its processing fee), not the price.
GET /orders
| Query | Default | Notes |
|---|---|---|
| limit | 25 | 1 to 100 |
| status | all | pending, confirmed, preparing, ready_for_pickup, out_for_delivery, fulfilled, cancelled |
The order object
| Field | Type | Notes |
|---|---|---|
| id | number | |
| status | string | One of the statuses above |
| items | array | Each with service_id, name, qty, unit_price |
| total | number | |
| pay_on_delivery | boolean | True when the customer pays on collection or delivery |
| fulfillment_type | string | pickup or delivery |
| delivery_address, delivery_notes | string or null | |
| tracking_number, carrier | string or null | |
| ready_at, estimated_ready_at | string or null | |
| tracking_url | string or null | The customer's own tracking page |
| client | object | name, email, phone |
| payment | object | status, amount_paid |
| notes, conversation_id, created_at | As for bookings |
Webhooks
GET /webhooks returns { "data": [endpoints], "events": [names], "opt_in_events": [names] }. events are the classic events, the ones * means; opt_in_events reach an endpoint only when it names them.
POST /webhooks
{ "url": "https://example.com/ordina/events", "events": ["booking.created", "order.created"], "description": "My app" }
urlmust be https.eventsis optional; leave it out, or send["*"], for every classic event. Opt-in events are never part of*: name them, alone or beside it, for example["*", "conversation.completed"]. An unknown name is refused with 400, alone or beside*, andfieldnames it:{ "error": "...", "field": "events[1]" }. A classic name beside*adds nothing, since*already includes it.descriptionis optional; up to 120 characters are kept.- An endpoint your app creates receives events without the customer's contact details. See Webhook events.
- Returns 201 with the endpoint and its
secret, once. - Up to 20 endpoints per business. Past that, the request is refused with 400.
DELETE /webhooks/{id} returns 204. It removes the endpoint when it is yours, and changes nothing otherwise, so a repeated unsubscribe is safe.
Payloads, signatures and retries: Webhook events and Verify signatures.
Connected actions
POST /actions registers an action the Secretary can use during a chat: a live lookup, or a write (a change in your system that the customer confirms first).
{
"name": "check_stock",
"title": "Stock check",
"description": "Live stock for a part at one of our branches, by part name or part number. Returns the quantity in stock, the unit price in USD, the expected restock date when it is out of stock, and a link to the product page. Our own branches only, not resellers.",
"url": "https://api.example.com/ordina/check-stock",
"parameters": {
"type": "object",
"properties": {
"item": { "type": "string", "description": "Part name or part number, for example M8 hex bolt or HB-M8-40" },
"location": { "type": "string", "description": "Branch", "enum": ["Northside", "Harbour Road", "Airport"] },
"quantity": { "type": "integer", "description": "How many the customer needs" }
},
"required": ["item"]
}
}
Returns 201 with the action (enabled: false) and its secret, once. Add "effect": "write", customer_fields and customer_proof to register a write action: see Connected actions, Write actions.
GET /actions returns { "data": [actions] }. GET /actions/{id} adds calls, the 10 most recent. PATCH /actions/{id} takes any of title, description, parameters, url, effect, customer_fields, customer_proof; a field you leave out keeps its value. Any change switches the action off until the owner approves it again, and sending the same values back changes nothing. enabled is the owner's: send it as it is, or leave it out. An enabled equal to the current value changes nothing; one that would switch the action on or off is refused with 400 and "field": "enabled", because only the owner switches an action on or off. DELETE /actions/{id} returns 204. All three answer 404 for an action another key or app registered.
A parameter whose name asks for the customer's contact details (email, phone, mobile, WhatsApp, address, a first, last or full name and the like) is refused with 400, and field names it: { "error": "...", "field": "parameters.properties.customer_email" }.
An effect, customer_fields or customer_proof that is not allowed is refused with 400, and field names it. A key the API does not know is ignored.
The action object: id, name, title, description, parameters, url, effect, customer_fields, customer_proof, enabled, source, failureCount, lastCalledAt, lastSuccessAt, lastFailureAt, createdAt, updatedAt. customer_fields and customer_proof come back under the names you send them with, so an action you read can be changed and sent back as a PATCH, enabled included. The other fields Ordina keeps, and name, are ignored in a PATCH. The secret is never returned again.
Everything else about actions: Connected actions.
Intakes
POST /intakes registers questions the Secretary collects from a customer for you.
{
"name": "quote_request",
"title": "Moving quote request",
"description": "Collect the details for a moving quote when the customer asks what a move would cost or asks for a quote. Not for customers asking about a move they already booked.",
"fields": [
{ "id": "move_date", "label": "What date would you like to move?", "type": "date", "required": true },
{ "id": "rooms", "label": "How many rooms are you moving?", "type": "number", "required": true },
{ "id": "email", "label": "Where should we send your quote?", "type": "email", "required": true, "help": "We email every quote within one working day." }
]
}
This is a shorter version of the example in Intakes, which asks three more questions.
Returns 201 with the intake (enabled: false). The owner switches it on. GET /intakes returns { "data": [intakes] }; GET /intakes/{id} returns one. PATCH /intakes/{id} takes any of title, description, fields; any change switches it off until the owner approves it again, and sending the same values back changes nothing. DELETE /intakes/{id} returns 204 and removes its responses. GET /intakes/{id}/responses returns { "data": [responses], "next_before": id or null }, newest first, 50 a page; pass ?before= with next_before for the next. All of them answer 404 for an intake another key or app registered.
Anything not allowed is refused with 400 and field naming it, such as "fields[1].options".
The intake object: id, name, title, description, fields (each { id, label, type, required, options?, help? }), enabled, createdAt, updatedAt. A response: id, conversation, answers, status, completed_at, created_at, the shape of the intake.completed event.
Everything else about intakes: Intakes.
Knowledge
PUT /knowledge/{key} with { "title": "...", "content": "..." } creates (201) or replaces (200) text the Secretary answers from. GET /knowledge lists yours: key, title, chars, updatedAt, createdAt. DELETE /knowledge/{key} returns 204, or 404 when you have nothing under that key. Keys are yours alone; another app's faq is a different text.
Details and limits: Push knowledge.
