Connected actions: give the Secretary live data

A connected action is an https endpoint on your system that a business's Secretary can call in the middle of a conversation to look something up. When a customer asks for something your action returns, the Secretary calls it, reads your answer, and replies from it.

1. RegisterPOST /api/v1/actions.
2. Build the endpointVerify, look up, answer JSON.
3. Owner testsWith real values, in the dashboard.
4. Owner switches it onLive on every channel.

When to use one

Use an action for data that is too large to copy, changes often, or should not leave your system in bulk: prices, stock, salaries, availability in another system, order status in your own store. For text that changes rarely, such as FAQs and policies, push knowledge instead.

Actions look things up. They do not book, charge, submit or change anything on the customer's behalf. Whatever your endpoint returns only becomes information the Secretary reads.

How a conversation uses it

1. A customer writes: "What does a mid-level product manager earn in Lagos?"
2. Before replying, the Secretary sees your actions' names, descriptions and parameters, and decides whether this message needs one.
3. It calls yours with { "role": "Product Manager", "level": "Mid", "location": "Lagos" }. Only values the customer actually gave are used; if a required one is missing, it asks the customer first.
4. Your endpoint answers with JSON.
5. The Secretary replies from your data: it quotes figures exactly, mentions a sample size, date or source when you include one, and shares a link only when your data has one.
6. If your endpoint fails, it tells the customer it could not check just now. It never fills the gap with a guess.

At most 2 action calls are made for one customer message.

Registering an action

POST /api/v1/actions
Authorization: Bearer ord_live_...
Content-Type: application/json

{
  "name": "lookup_salary",
  "title": "Salary lookup",
  "description": "Salary range in Nigeria for a job title, with optional seniority and city. Returns the median and the 25th and 75th percentile monthly pay in NGN, the number of verified entries, the last update date and a link to the full page.",
  "url": "https://api.example.com/ordina/lookup-salary",
  "parameters": {
    "type": "object",
    "properties": {
      "role": { "type": "string", "description": "Job title, for example Product Manager" },
      "level": { "type": "string", "description": "Seniority", "enum": ["Junior", "Mid", "Senior", "Lead"] },
      "location": { "type": "string", "description": "City in Nigeria, for example Lagos" },
      "years": { "type": "integer", "description": "Years of experience" }
    },
    "required": ["role"]
  }
}

The response is 201 with the action and its secret. Store the secret now; it is never shown again.

Field	Rules
name	3 to 40 characters: lower-case letters, digits, underscores, starting with a letter. Unique within the business.
title	Up to 60 characters. What the owner sees in their dashboard.
description	20 to 600 characters. What the Secretary reads to decide when to call it.
url	A public https address. No credentials in it, no internal addresses, no redirects.
parameters	Optional. See below.

A business can have up to 10 actions.

Parameters

A small, flat subset of JSON Schema: an object whose properties are each one of

type	Notes
string	Up to 200 characters arrive. Add enum (1 to 50 values) to allow only those.
number	Commas and spaces are removed, so "1,200" arrives as 1200.
integer	A whole number. 2.5 is refused.
boolean	true or false.

Every property needs a description. Up to 8 properties. Nested objects and arrays are not supported, because the Secretary fills parameters from a conversation and a flat form is what it fills reliably.

Before anything reaches you, Ordina checks the Secretary's values against your schema: unknown properties are dropped, an enum value is matched without regard to case and sent exactly as you wrote it, and a call with a missing required value or a wrong type is never sent.

Writing a good description

The description is the only thing the Secretary has to decide when to call you. Say:

• What it returns, with the units and currency: "monthly pay in NGN".
• What it needs: "for a job title, with optional seniority and city".
• What it does not cover, if customers might assume it does: "Nigeria only".

Avoid instructions such as "always call this" or "tell the customer to sign up". They are ignored at best, and they make a reviewer less likely to switch your action on.

What your endpoint receives

POST https://api.example.com/ordina/lookup-salary
Content-Type: application/json
Accept: application/json
User-Agent: Ordina-Actions/1.0 (+https://www.useordina.com)
X-Ordina-Action: lookup_salary
X-Ordina-Call: call_k2D8...
X-Ordina-Signature: t=1759312800,v1=9a41...

{
  "id": "call_k2D8...",
  "action": "lookup_salary",
  "arguments": { "role": "Product Manager", "level": "Mid", "location": "Lagos" },
  "business": { "id": "6f1c...", "handle": "brightsalon" },
  "conversation": { "id": "c0a9...", "channel": "web" },
  "test": false,
  "created_at": "2026-10-01T10:00:00.000Z"
}

Field	Notes
id	Unique per call. Matches X-Ordina-Call.
arguments	Only your declared properties, already type-checked. Required ones are always present.
business	Which business's Secretary is asking. One action belongs to one business.
conversation	The conversation id and channel (web, whatsapp, telegram, instagram, messenger, email). Null for a test.
test	True when the owner pressed Test in the dashboard.

Verify X-Ordina-Signature with the action's secret: see Verify signatures. No customer name, email or phone is sent.

What your endpoint returns

• Status 2xx, a JSON body, within 5 seconds, at most 16 KB.
• Any JSON shape works. Include what a careful answer needs: the figures, their unit and currency, the sample size, the date, a link.

{
  "role": "Product Manager",
  "level": "Mid",
  "location": "Lagos",
  "currency": "NGN",
  "period": "monthly",
  "median": 850000,
  "p25": 650000,
  "p75": 1100000,
  "entries": 23,
  "updated": "2026-09-28",
  "url": "https://example.com/salaries/product-manager?level=mid&city=lagos"
}

• Nothing found is still a 200, said plainly: { "found": false, "reason": "Fewer than 5 verified entries for this role in Lagos" }. The Secretary then says so instead of guessing.
• Keep it small. Only the first 4,000 characters of your compact JSON reach the Secretary; anything after that is cut.

These count as a failure, and the Secretary tells the customer it could not check: a non-2xx status, a redirect, a body that is not JSON, a body over 16 KB, or no answer within 5 seconds.

Approval: switching it on

Every action arrives switched off. The business owner:

1. Opens Integration, then Connected actions.
2. Reads your title and description, and presses Test with real values. They see exactly what the Secretary would read.
3. Presses Switch on.

Only the owner can switch an action on or off; the API cannot. If you change an action's url, it switches itself off until the owner approves the new address. Changing the title, description or parameters keeps it on. Tell the owner when you change the description: it changes when the Secretary calls you.

Watching it work

• GET /api/v1/actions/{id} returns the 10 most recent calls: arguments, status (ok, error, timeout, rejected), HTTP status, time taken, any error, and the start of your response.
• The owner sees the same history in the dashboard, with a warning after 3 failures in a row.
• rejected means Ordina did not send the call because the Secretary's values did not fit your schema. It does not count against your endpoint.

Checklist before you hand it to the owner

• The endpoint verifies the signature and rejects old timestamps.
• It answers in well under 5 seconds, including a cold start.
• "Nothing found" is a 200 with a reason, not a 404.
• The response carries units, currency, sample size and date where they matter.
• test: true calls work, and do not count as real usage in your analytics.
• The description says what it returns and what it needs, in plain words.