Intakes: have the Secretary collect answers for you

An intake is a short list of questions a business's Secretary asks a customer in conversation, for your app: the details for a quote, a callback request, a salary submission. When the customer has answered every required question, Ordina sends you the answers.

1. RegisterPOST /api/v1/intakes.
2. Owner switches it onAfter seeing every question.
3. The Secretary asksWhen a conversation fits.
4. You get the answersintake.completed, or the responses endpoint.

When to use one

Use an intake when you need answers from the customer, in a set shape, handed to your system. Use a connected action when the Secretary needs your data, or needs your system to do something for the customer.

How a conversation uses an intake

1. A customer says something your description covers: "I'd like to add my salary to your index."
2. The Secretary tells the customer what it will ask and that the answers go to the business, then asks your questions one at a time.
3. Each answer is checked by its type (an email address, a phone number with its country code, a number, a date, one of your choices), and earlier answers are kept unless the customer changes them.
4. When every required question has a valid answer, Ordina stores the response, sends you intake.completed, and thanks the customer in its own words.
5. A customer who says they do not want to go on stops it, and nothing is sent. An intake left unfinished for 24 hours is dropped.

Before anything is sent, Ordina checks the intake is still switched on and unchanged since the conversation started it. If it is not, nothing is sent and the Secretary apologises to the customer.

Registering an intake

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

{
  "name": "salary_submission",
  "title": "Salary submission",
  "description": "Collect a salary submission when the customer offers to share what they earn. Not for customers who only ask what a role pays.",
  "fields": [
    { "id": "role", "label": "What is your job title?", "type": "text", "required": true },
    { "id": "level", "label": "How senior are you?", "type": "select", "required": true, "options": ["Junior", "Mid", "Senior", "Lead"] },
    { "id": "monthly_pay", "label": "What is your monthly pay, in naira?", "type": "number", "required": true },
    { "id": "email", "label": "Where should we send your report?", "type": "email", "required": false, "help": "Optional. We email the full report for the role." }
  ]
}

The response is 201 with the intake, switched off:

{
  "id": 12,
  "name": "salary_submission",
  "title": "Salary submission",
  "description": "Collect a salary submission when the customer offers to share what they earn. Not for customers who only ask what a role pays.",
  "fields": [ ... ],
  "enabled": false,
  "createdAt": "2026-10-15T10:00:00.000Z",
  "updatedAt": "2026-10-15T10:00:00.000Z"
}

Field	Rules
name	3 to 40 characters: lower-case letters, digits, underscores, starting with a letter. Unique within the business. It cannot be changed later.
title	3 to 80 characters. What the owner sees in their dashboard.
description	20 to 500 characters. What the Secretary reads to decide when to start it: say when, and when not.
fields	1 to 12 questions, below. At least one must be required.

A business can have up to 5 intakes, from every key and app together.

Fields

Key	Rules
id	1 to 40 characters: lower-case letters, digits, underscores, starting with a letter. Unique within the intake. The answer comes back under it.
label	Up to 80 characters. The question, in your words.
type	text, textarea, number, email, phone, date or select.
required	true or false (the default).
options	For select only: 2 to 20 different choices, each up to 80 characters.
help	Optional, up to 200 characters: a hint the Secretary may use when it asks.

type	What the Secretary accepts
text	A short answer
textarea	A longer answer
number	A number
email	An email address
phone	A phone number with its country code
date	A date
select	One of your options

Anything not allowed is refused with 400, and field names it: { "error": "fields[1].options must be 2 to 20 different choices, each up to 80 characters.", "field": "fields[1].options" }. Keys the API does not know are ignored.

Contact details

Unlike a connected action, an intake may ask for the customer's email address or phone number: it exists to collect details for you. The owner approves them explicitly. When they switch the intake on, Ordina lists every question and names the contact details you will receive ("This app will receive the customer's email and phone number"), and any other question that asks who the customer is, such as a full name, a home address or a date of birth.

Ask only for what you need: an intake that asks for less is easier to approve.

An email or phone answer carries proof: "verified" when the channel proved it (a phone number the customer writes from on WhatsApp, an email address they send from, the same rule as write actions), or "stated" when the customer typed it.

Approval: switching it on

Every intake arrives switched off. The business owner opens Integration, then Connected actions, reads your intake under Intakes, and switches it on after a check that lists every question and the contact details you receive. Only the owner can switch an intake on or off; the API cannot.

Any change you make through PATCH /intakes/{id}, to the title, the description or a question (added, removed, changed or moved), switches the intake off until the owner approves it again. The dashboard shows them what changed, question by question. Sending the same values back changes nothing. Tell the owner when you change an intake, so it is not off for long.

Revoking your key, or the owner disconnecting your app, also switches your intakes off.

Changing and removing

• PATCH /api/v1/intakes/{id} takes any of title, description and fields. A key you leave out keeps its value; fields replaces the whole list. name cannot change and enabled is the owner's, but you can send both back as they are, so an intake you read can be edited and sent back.
• DELETE /api/v1/intakes/{id} removes the intake and the responses stored with it: 204.
• GET, PATCH and DELETE answer 404 for an intake another key or app registered. Intakes are never shared: each belongs to the key or app that made it.

Receiving the answers

The intake.completed event

Subscribe a webhook endpoint to intake.completed by name, for example POST /api/v1/webhooks with "events": ["intake.completed"]. It is an opt-in event: * does not include it. You receive it only for your own intakes.

{
  "intake": { "id": 12, "name": "salary_submission", "title": "Salary submission" },
  "response_id": 3051,
  "conversation": { "id": "c0a9...", "channel": "whatsapp" },
  "answers": [
    { "id": "role", "label": "What is your job title?", "type": "text", "value": "Product Manager" },
    { "id": "level", "label": "How senior are you?", "type": "select", "value": "Mid" },
    { "id": "monthly_pay", "label": "What is your monthly pay, in naira?", "type": "number", "value": "850000" },
    { "id": "email", "label": "Where should we send your report?", "type": "email", "value": "tunde@example.com", "proof": "stated" }
  ],
  "completed_at": "2026-10-15T10:00:04.000Z"
}

This is the data of the usual envelope, signed and retried like every event: see Webhook events and Verify signatures. Every value is text. An optional question can be missing from answers when the customer did not answer it. Use response_id to ignore a delivery you have already handled.

The responses endpoint

GET /api/v1/intakes/{id}/responses returns the intake's responses, newest first, 50 a page:

{
  "data": [
    {
      "id": 3051,
      "conversation": { "id": "c0a9...", "channel": "whatsapp" },
      "answers": [ { "id": "role", "label": "What is your job title?", "type": "text", "value": "Product Manager" } ],
      "status": "completed",
      "completed_at": "2026-10-15T10:00:04.000Z",
      "created_at": "2026-10-15T10:00:04.100Z"
    }
  ],
  "next_before": 3001
}

Each response has the shape of the event's data; its id is the event's response_id. For the next page, pass next_before as ?before=3001; it is null on the last page. Use it to catch up after your endpoint was down.

Where intakes run

On every chat channel: the chat page, the website widget, WhatsApp, SMS, Telegram, Instagram, Messenger and email. Not on phone calls, and not through AI assistants connected to the business (MCP), yet.

Checklist before you hand it to the owner

• The description says when to start the intake, and when not to.
• Each label is a question a customer can answer in one message.
• It asks for no more contact details than you need.
• An endpoint is subscribed to intake.completed by name and verifies the signature.
• A repeated delivery of the same response_id changes nothing in your system.