Ordo's API

Try it

Give the key a name, for example "Zapier" or "Our website". Choose Whose key it is, and click Make the key. Copy the key at once. Ordo shows it only this one time.

How it works

• Whose key: each key belongs to one person, and it can do only what this person can do in Ordo. A sales rep's key sees the rep's own records. A manager's key sees their team's records. An admin's key sees everything.
• The same rules: a key follows the same rules as the screens. Change history shows each change as made by the key's person.
• Shown once: Ordo shows a new key only one time. Copy it at once, and put it in the other program.
• Take back: click Take back next to a key. It stops working at once.
• Every admin knows: when someone makes a key, every other admin is told in the bell.

Send the key with each request

A request is one message from a program to Ordo, for example "send me the list of companies". The program sends the key with each request, in its Authorization header. A header is a line at the start of the request.

GET https://app.ordo-crm.com/api/v1/companies
Authorization: Bearer ordo_w1a2b3c4d5e6_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Ordo Cloud: the address is https://app.ordo-crm.com. The key itself says which company it is for.
• Ordo On-site: the address is your own Ordo, for example https://ordo.yourcompany.com. A program outside your office can reach it only if your Ordo is open to the internet. The Setup guide shows how, in "Use Ordo outside the office".

Send JSON with Content-Type: application/json. JSON is a simple way to write data as text. Times are in UTC, like 2026-11-03T08:00:00Z. Dates are like 2026-11-03.

Limits

• Each key can send at most 60 requests a minute.
• The whole company can send at most 10,000 requests a day. The day starts at midnight UTC.

Past a limit, Ordo answers 429 with a Retry-After header. It is the number of seconds to wait.

What a program can do

<things> is companies, people, deals, activities (meetings and tasks) or notes. Nothing is deleted through the API.

Lists

A list comes in pages:

{ "data": [ { "id": 7, "name": "Acme Robotics", "...": "..." } ], "has_more": true, "next_offset": 50 }

To choose what a list shows, add these to the address after a ?, for example /api/v1/[email protected]. Put & between two of them.

The fields

A field is one part of a record, for example its name or its owner. The API uses the same names as Ordo's screens: companies, people and deals.

Companies

People

Deals

Activities: meetings and tasks

Ordo doesn't make the same open task twice. The same open task has the same subject, for the same record and person. Then Ordo answers with the task that is already there, with "existing": true.

Notes: a record's updates

• GET /api/v1/notes?company_id=7 (or person_id=, deal_id=): a record's updates, newest first.
• POST /api/v1/notes with { "deal_id": 42, "body": "Called Jane: budget approved" }. You can also send activity_id (one of the record's meetings or tasks) and on_date (an earlier day).
• PATCH /api/v1/notes/<id> with a new body. Only the person who wrote it, or an admin, can do this.

When something is wrong

Ordo answers with a status code and a sentence that says what to do. A status code is a number that says how the request went.

{ "error": "There's no field colour on companies. The fields are: name, status, ..." }

Webhooks: Ordo tells your program

A webhook is an address of your program. When something happens, Ordo sends a short message to it: a POST request with JSON.

Add a webhook

• An admin adds it in Settings → Connections → New webhook: the address, and what to send. Ordo then shows its signing secret (whsec_…). An admin can see it again with Show secret.
• A program can add its own webhook with its API key, and remove it when it is done. POST /api/v1/webhooks with { "url": "https://...", "events": ["deal.won"] } answers with its id and secret. DELETE /api/v1/webhooks/<id> removes it. GET /api/v1/webhooks lists the key's own webhooks. When a key is taken back, its webhooks go with it.

A webhook sends only what its person may see. Ordo Cloud sends only to public https:// addresses.

What Ordo sends

The message

{
  "id": "evt_5xKq2c9TfQ8a",
  "event": "deal.won",
  "created_at": "2026-11-03T08:00:00Z",
  "data": { "id": 42, "name": "40 cameras", "company": "Acme Robotics", "stage": "Won", "amount": 48000, "...": "..." }
}

data is the record as the API shows it. Your program answers with any 2xx code within 10 seconds. A 2xx code, like 200, means that all is well. If your program doesn't answer, Ordo tries again after 1 minute, after 10 minutes, and then every hour. A webhook that fails for a whole day is turned off, and the admins are told in the bell.

Settings → Connections → What was sent shows each message and how it went, with Send again.

Check that a message came from Ordo

Each message has this header:

X-Ordo-Signature: t=1762156800,v1=5257a869e7ec...

v1 is the HMAC-SHA256, in hex, of the text <t>.<the body as sent>, made with the webhook's secret. HMAC-SHA256 is a standard way to sign a text with a secret. Make the same in your program, and compare the two. Also check that t is recent, for example within 5 minutes. Then nobody can send an old message again.

JavaScript (Node):

import crypto from "node:crypto";
function fromOrdo(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const want = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(t)) < 300 && v1?.length === want.length && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(v1));
}

Python:

import hashlib, hmac, time
def from_ordo(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    want = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(parts["t"])) < 300 and hmac.compare_digest(want, parts["v1"])

Other headers: X-Ordo-Event (the event) and X-Ordo-Delivery (the message's number in What was sent).

Make, n8n and Zapier

Make, n8n and Zapier each have a step that sends a web request, and a step that waits for a webhook. In Make, they are the HTTP and Webhooks modules. In n8n, they are the HTTP Request and Webhook nodes. In Zapier, both are in Webhooks by Zapier.

• To read or change records in Ordo: use the step that sends a web request. Put the API key in its Authorization header, as above.
• To hear from Ordo: use the step that waits for a webhook. Copy its address, and add it in Ordo as a new webhook.

Good to know

• The API and webhooks are in every plan: Cloud, Cloud + AI and On-site. They cost nothing extra.
• Version 1 of the API stays as it is. New fields may come, but no field is renamed or removed.
• Ordo doesn't keep the key itself, only a scrambled copy that can't be turned back. So nobody can see a key again, an admin included.

Questions

Read next