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" }
  • url must be https. events is 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 *, and field names it: { "error": "...", "field": "events[1]" }. A classic name beside * adds nothing, since * already includes it.
  • description is 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.

Did this answer it?If not, write to help@useordina.com with your handle, or contact us. A person replies.
Contact us