The Ordina API: give your software a front desk that can act

Every business on Ordina has an AI Secretary that answers customers on its booking page, website chat, Telegram, email and phone calls, books from live availability and takes payment. The Ordina API lets your software work with that Secretary: read what it booked, hear what happened in each conversation, teach it what your system knows, and let it look things up or make changes in your system once a customer says yes.

This post is a map of the whole API. Every request below comes from our developer docs, which hold the full reference.

What you can build

Everything is scoped to one business, and the API is part of the Business plan ($39 a month, or $390 a year).

Two ways in: API keys and Connect to Ordina

API keys suit your own scripts or a setup the owner does by hand. The owner opens Integration, then API keys, creates a key, and copies it once. Ordina stores only a SHA-256 fingerprint, so nobody can show it again. A business can hold up to 10 active keys.

curl https://www.useordina.com/api/v1/me \
  -H "Authorization: Bearer ord_live_YOUR_KEY"

{ "id": "6f1c...", "handle": "brightsalon", "name": "Bright Salon", "currency": "NGN", "country": "NG" }

Connect to Ordina is for platforms that many businesses will connect. It is standard OAuth 2.1 with PKCE (S256), so any OAuth library works. You register your app once at /api/oauth/register, send the owner to /oauth/authorize with scope=api, and swap the code for tokens. The owner sees exactly what your app can do before they approve, and only the owner can approve. Access tokens last an hour; refresh tokens last 90 days and rotate on every use.

Either way, what you create belongs to your key or app. Another app connected to the same business cannot see, change or delete your webhooks, actions, intakes or knowledge.

Read: appointments and orders

Two list endpoints return the data most integrations need, newest first, up to 100 at a time:

curl "https://www.useordina.com/api/v1/appointments?status=confirmed&since=2026-10-01&limit=5" \
  -H "Authorization: Bearer ord_live_YOUR_KEY"

A booking carries the service, the client, the payment status, the business's own reschedule and cancel links, and the conversation_id it came from. Dates and times are in the business's own time zone, and amounts are in its own currency, which GET /me tells you.

Listen: webhooks

Subscribe an https URL and Ordina posts each event as it happens:

curl -X POST https://www.useordina.com/api/v1/webhooks \
  -H "Authorization: Bearer ord_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/ordina/events","events":["booking.created","lead.created"]}'

There are 14 classic events (bookings created, rescheduled, cancelled and completed; order stages; payment.received; lead.created; review.created; form.submitted), and * means all of them. Nine more are opt-in: conversation.completed, intake.completed, the action.* events and app.disconnected. You only receive those when you name them, so an existing subscription never changes under you. We cover them in depth in Getting every conversation into your CRM.

Answer with any 2xx within 10 seconds. A failed delivery is tried again up to five more times over about 15 hours. Every event has a unique id, so you can ignore a repeat.

Trust: signatures

Every webhook delivery and every action call is signed:

X-Ordina-Signature: t=1790848800,v1=5f2c...e9a1

v1 is the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the secret you were shown once. Here is the check in Node.js, from the docs:

import crypto from "node:crypto";

export function verifyOrdina(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`, "utf8").digest("hex");
  return expected.length === parts.v1.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Hash the raw bytes before any JSON parsing, and reject timestamps more than five minutes old. Python and PHP versions are in the signatures guide.

Act: connected actions

A connected action is an https endpoint on your system that the Secretary can call mid-conversation. You describe it in plain words and declare flat parameters; the Secretary decides when a customer's message needs it.

{
  "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 and a link to the product page.",
  "url": "https://api.example.com/ordina/check-stock",
  "parameters": {
    "type": "object",
    "properties": {
      "item": { "type": "string", "description": "Part name or part number" },
      "location": { "type": "string", "description": "Branch", "enum": ["Northside", "Harbour Road", "Airport"] }
    },
    "required": ["item"]
  }
}

A lookup answers with JSON within 5 seconds, and the Secretary replies from your data, quoting figures exactly. If your endpoint fails, it says it could not check. It never guesses.

A write ("effect": "write") opens a ticket, books a callback or saves a request in your system. It runs only after the customer says yes to exactly what will be sent, and each confirmed call carries an Idempotency-Key. We explain that design in Why our AI never acts without a yes.

Every action arrives switched off. The owner tests it with real values in the dashboard and switches it on. Any change you make through the API switches it off again until they approve.

Collect: intakes

An intake is a short list of typed questions (text, number, email, phone, date or a choice) that the Secretary asks in conversation when the customer's request fits your description. A moving company might collect the date, the number of rooms and an email for the quote. When every required answer is in, Ordina sends intake.completed, and you can catch up any time through GET /intakes/{id}/responses.

Teach: pushed knowledge

For text that changes rarely, push it instead of uploading it by hand:

PUT /api/v1/knowledge/delivery-areas
{ "title": "Where we deliver and how long it takes", "content": "We deliver to every address in the city..." }

Pushing the same key again replaces it, and an unchanged push returns "unchanged": true, so a nightly sync is cheap. Pushed text is treated as information, never as instructions, and the business's own settings (hours, prices, services) always win.

What the API will not do

The API never creates, changes or cancels bookings, orders, payments or settings on Ordina. Those go through the booking page, the Secretary and the owner's dashboard. A leaked key can read data, but it cannot move money or change what a customer was promised. A partner app also receives events without customers' names, emails or phone numbers.

Getting started

1. Start a 7-day free trial (no card needed), then move to Business from your dashboard.
2. Create a key under Integration, API keys, and call GET /me.
3. Subscribe a webhook, verify its signature, and send a test ping from the dashboard.
4. Add one lookup, test it in the dashboard and switch it on. Then talk to the Secretary on the business's booking page, as a customer would.

The partner integration walkthrough puts all of this in order, with a go-live checklist.

FAQ

Which plan includes the Ordina API?

The Business plan, at $39 a month or $390 a year. API keys, webhooks, Zapier, connected actions and intakes are all part of it. If a plan lapses, requests return 403 until it is active again.

Can the API create bookings?

No. Bookings, orders and payments go through Ordina's own checks: the booking page, the Secretary and the dashboard. Your system can still act on its own side through write actions, after the customer confirms.

Should I use an API key or OAuth?

Use an API key for your own scripts or a single business. Use Connect to Ordina (OAuth 2.1 with PKCE) if many businesses will connect your platform, so nobody copies keys around and owners can disconnect you at any time.

How do I stop processing the same webhook twice?

Store each event's id and skip one you have seen. For intakes, use response_id. For write actions, treat the Idempotency-Key as the identity of the request.

How do I test without affecting real customers?

Testing happens on a real business account, so a trial business of your own is the easiest place to start. Owners can press Test on an action, which sends a signed call with test: true that must change nothing, and the webhook Test button sends a ping to one endpoint.