API reference

Create a confirmation

Creates a confirmation from an order and schedules its plan. The first step goes out on the schedule set by cadence.

POST/v1/confirmations

Send the order as you'd hand it to a carrier: who the customer is, what's coming, when, and where. AnyoneIn validates everything at once, then returns the new confirmation with its plan.

curl -X POST https://api.anyonein.co.uk/v1/confirmations \
  -H "Authorization: Bearer $ANYONEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "HF-100482",
    "brand": {
      "name": "Harlow & Finch",
      "colors": { "primary": "#1F3A5F" },
      "supportEmail": "help@harlowandfinch.co.uk",
      "tone": "warm, clear and brief"
    },
    "customer": {
      "name": "Priya Shah",
      "phone": "07700 900123",
      "email": "priya@example.com"
    },
    "order": {
      "ref": "HF-100482",
      "type": "delivery",
      "date": "2026-10-13",
      "window": { "from": "08:00", "to": "12:00" },
      "items": [{ "name": "Marlow 3-seat sofa", "qty": 1, "sku": "MAR-3S-OAT" }],
      "address": { "line1": "14 Albert Road", "city": "Bristol", "postcode": "BS2 0XA" },
      "rescheduleOptions": [
        { "date": "2026-10-15", "window": { "from": "08:00", "to": "12:00" } }
      ]
    },
    "cadence": "standard",
    "webhookUrl": "https://example.com/webhooks/anyonein"
  }'

// Node 18+ (global fetch)
const res = await fetch('https://api.anyonein.co.uk/v1/confirmations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ANYONEIN_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalId: 'HF-100482',
    brand: {
      name: 'Harlow & Finch',
      colors: { primary: '#1F3A5F' },
      supportEmail: 'help@harlowandfinch.co.uk',
      tone: 'warm, clear and brief',
    },
    customer: { name: 'Priya Shah', phone: '07700 900123', email: 'priya@example.com' },
    order: {
      ref: 'HF-100482',
      type: 'delivery',
      date: '2026-10-13',
      window: { from: '08:00', to: '12:00' },
      items: [{ name: 'Marlow 3-seat sofa', qty: 1, sku: 'MAR-3S-OAT' }],
      address: { line1: '14 Albert Road', city: 'Bristol', postcode: 'BS2 0XA' },
      rescheduleOptions: [{ date: '2026-10-15', window: { from: '08:00', to: '12:00' } }],
    },
    cadence: 'standard',
    webhookUrl: 'https://example.com/webhooks/anyonein',
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(body.errors?.join(' ') ?? body.error);
console.log(body.confirmation.id, body.confirmation.status); // cf_7d2a9c41e0b3f658 scheduled

import os
import requests

res = requests.post(
    "https://api.anyonein.co.uk/v1/confirmations",
    headers={"Authorization": f"Bearer {os.environ['ANYONEIN_KEY']}"},
    json={
        "externalId": "HF-100482",
        "brand": {
            "name": "Harlow & Finch",
            "colors": {"primary": "#1F3A5F"},
            "supportEmail": "help@harlowandfinch.co.uk",
            "tone": "warm, clear and brief",
        },
        "customer": {"name": "Priya Shah", "phone": "07700 900123", "email": "priya@example.com"},
        "order": {
            "ref": "HF-100482",
            "type": "delivery",
            "date": "2026-10-13",
            "window": {"from": "08:00", "to": "12:00"},
            "items": [{"name": "Marlow 3-seat sofa", "qty": 1, "sku": "MAR-3S-OAT"}],
            "address": {"line1": "14 Albert Road", "city": "Bristol", "postcode": "BS2 0XA"},
            "rescheduleOptions": [{"date": "2026-10-15", "window": {"from": "08:00", "to": "12:00"}}],
        },
        "cadence": "standard",
        "webhookUrl": "https://example.com/webhooks/anyonein",
    },
    timeout=15,
)
body = res.json()
if not res.ok:
    raise RuntimeError(body.get("errors") or body["error"])
print(body["confirmation"]["id"], body["confirmation"]["status"])

<?php
$payload = [
    'externalId' => 'HF-100482',
    'brand' => [
        'name' => 'Harlow & Finch',
        'colors' => ['primary' => '#1F3A5F'],
        'supportEmail' => 'help@harlowandfinch.co.uk',
        'tone' => 'warm, clear and brief',
    ],
    'customer' => ['name' => 'Priya Shah', 'phone' => '07700 900123', 'email' => 'priya@example.com'],
    'order' => [
        'ref' => 'HF-100482',
        'type' => 'delivery',
        'date' => '2026-10-13',
        'window' => ['from' => '08:00', 'to' => '12:00'],
        'items' => [['name' => 'Marlow 3-seat sofa', 'qty' => 1, 'sku' => 'MAR-3S-OAT']],
        'address' => ['line1' => '14 Albert Road', 'city' => 'Bristol', 'postcode' => 'BS2 0XA'],
        'rescheduleOptions' => [['date' => '2026-10-15', 'window' => ['from' => '08:00', 'to' => '12:00']]],
    ],
    'cadence' => 'standard',
    'webhookUrl' => 'https://example.com/webhooks/anyonein',
];

$ch = curl_init('https://api.anyonein.co.uk/v1/confirmations');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ANYONEIN_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 201) {
    throw new RuntimeException(implode(' ', $body['errors'] ?? [$body['error']]));
}
echo $body['confirmation']['id'];

Response201 Created

{
  "confirmation": {
    "id": "cf_7d2a9c41e0b3f658",
    "createdAt": "2026-09-27T14:02:11.482Z",
    "source": "api",
    "externalId": "HF-100482",
    "brand": {
      "name": "Harlow & Finch",
      "colors": { "primary": "#1F3A5F" },
      "supportEmail": "help@harlowandfinch.co.uk",
      "tone": "warm, clear and brief"
    },
    "customer": {
      "name": "Priya Shah",
      "first": "Priya",
      "phone": "+447700900123",
      "email": "priya@example.com"
    },
    "order": {
      "ref": "HF-100482",
      "type": "delivery",
      "date": "2026-10-13",
      "window": { "from": "08:00", "to": "12:00" },
      "items": [{ "name": "Marlow 3-seat sofa", "qty": 1, "sku": "MAR-3S-OAT" }],
      "address": { "line1": "14 Albert Road", "city": "Bristol", "postcode": "BS2 0XA" },
      "requiresSignature": true,
      "notes": "",
      "rescheduleOptions": [
        { "date": "2026-10-15", "window": { "from": "08:00", "to": "12:00" } }
      ]
    },
    "channels": { "email": true, "sms": true, "call": true },
    "smsVia": "sms",
    "cadence": "standard",
    "webhookUrl": "https://example.com/webhooks/anyonein",
    "status": "scheduled",
    "outcome": null,
    "steps": [
      { "id": "st_4be1a09c", "channel": "email", "dueAt": "2026-10-10T09:00:00.000Z", "state": "pending" },
      { "id": "st_91c3d27e", "channel": "sms", "dueAt": "2026-10-11T09:00:00.000Z", "state": "pending" },
      { "id": "st_0a6f58b2", "channel": "call", "dueAt": "2026-10-12T10:00:00.000Z", "state": "pending" }
    ],
    "events": [
      {
        "id": "ev_3f0c9a21d4",
        "at": "2026-09-27T14:02:11.482Z",
        "kind": "system",
        "text": "Confirmation created via the API. Plan: Email → Text → Call."
      }
    ],
    "call": null,
    "callAttempts": 0,
    "updatedAt": "2026-09-27T14:02:11.483Z",
    "links": { "customer": "https://api.anyonein.co.uk/c/7d2a9c41e0b3f658.Qm9vS2VkRm9yVHVlc2RheQ" },
    "emailThread": false
  }
}

Request body

Only a handful of fields are required: customer.name, a way to reach the customer on each channel you use, order.date and at least one item. Unknown fields are ignored. The body can be up to 40 KB.

externalIdstringoptional: Your reference for this job, up to 80 characters. Returned on every response and webhook so you can match it back. It isn't checked for uniqueness.
cadencestringoptional: standard for real customers: email three days out, text two days out, call the day before, in sensible hours. demo runs the steps about 90 seconds apart, for testing. The current release defaults to demo, so always send it. See cadence.
webhookUrlstringoptional: An https URL that receives confirmation.updated events for this confirmation. See Webhooks.
smsViastringoptional: sms (the default) or whatsapp. WhatsApp to customers who haven't messaged you first needs approved templates in production.

customer

customer.namestringrequired: Full name, up to 80 characters.
customer.firststringoptional: What the agent calls them, up to 40 characters. Defaults to the first word of name.
customer.phonestringrequired for texts and calls: A mobile number in any common format. Numbers without a country code are treated as UK. Stored in E.164.
customer.emailstringrequired for email: A valid email address. Stored in lower case.

order

order.datestringrequired: The delivery or collection date, YYYY-MM-DD. It can be today, but not in the past or more than 120 days away.
order.itemsarrayrequired: One to 20 items. Each has a name (up to 80 characters), an optional qty (1 to 99, default 1) and an optional sku (up to 40 characters). Items without a name are dropped.
order.typestringoptional: delivery (the default) or collection. Collections ask for someone to hand the item over and for it to be ready to go.
order.windowobjectoptional: { "from": "08:00", "to": "12:00" }, 24-hour UK time, with from before to. If it's missing or invalid, messages say "during the day".
order.refstringoptional: The order number the customer knows, up to 40 characters. Shown in the email.
order.addressobjectoptional: line1 (up to 120 characters), city (60) and postcode (10, stored in capitals). Shown in the email. On a call the agent only reads the first line, and only if asked.
order.requiresSignaturebooleanoptional: Defaults to true: someone aged 18 or over must be in, and the item can't be left in a safe place or with a neighbour. Send false to make a signature preferred rather than required.
order.notesstringoptional: Up to 500 characters for the agent, such as "Third-floor flat, no lift". Used to answer questions; not sent to the customer as written.
order.rescheduleOptionsarrayoptional: Up to four other slots the agent can offer, each { "date": "YYYY-MM-DD", "window": { "from", "to" } }. Dates follow the same rules as order.date. If the customer picks one, the confirmation ends rescheduled and order.date and order.window are updated.

channels

channels.emailbooleanoptional: Default true.
channels.smsbooleanoptional: Default true. A text, or WhatsApp with smsVia: "whatsapp".
channels.callbooleanoptional: Default true. A natural AI phone call that says it's automated, checks it's speaking to the right person, and leaves a voicemail if a machine answers.

At least one channel must be on. Leave a channel out of the object and it stays on, so { "call": false } means email and text only.

brand

Every message goes out in your name, never ours.

brand.namestringoptional: Your trading name, up to 60 characters. The agent introduces itself as your automated assistant. Always send it.
brand.colors.primarystringoptional: A hex colour such as #1F3A5F, used for the buttons in the email and on the customer page.
brand.supportEmailstringoptional: Shown in the email footer, up to 120 characters.
brand.tonestringoptional: How the agent should sound, up to 160 characters, such as "warm, clear and brief".

What happens next

The response is 201 Created with the confirmation: status: "scheduled", outcome: null and one steps entry per channel with its dueAt.

From there, the plan runs on its own. The first step goes out, the status moves to in_progress, and any reply pauses the plan while the agent reads it. When there's a clear answer, or everyone has been tried and nobody answered, the confirmation closes and your webhookUrl gets a confirmation.updated event.

Validation errors

If anything is wrong, nothing is created. You get a 422 listing every problem at once, in errors, and the same messages joined together in error.

Message	Cause
`Turn on at least one channel.`	Every channel in `channels` is `false`
`customer.name is required.`	Missing or empty name
`customer.phone must be a valid mobile number for texts and calls.`	Texts or calls are on and the number is missing or invalid
`customer.email must be a valid email address.`	Email is on and the address is missing or invalid
`order.date must be a date like 2026-10-14.`	Not a `YYYY-MM-DD` date
`order.date is in the past.`	Before today, UK time
`order.date is more than 120 days away.`	Too far ahead
`order.rescheduleOptions[0].date …`	The same three date rules, for each offered slot
`order.items needs at least one item with a name.`	No items, or none with a name
`webhookUrl must be an https URL.`	Not a valid URL, or not `https`

Other errors, such as 400 for a body that isn't JSON or 429 when you've created too many in an hour, are listed in Errors and Rate limits.

Roadmap

Idempotency keys, so a retried request can't create a second confirmation, are coming. Until then, see Idempotency for how to retry safely.

Response422 Unprocessable Entity

{
  "error": "customer.email must be a valid email address. order.date is in the past. order.items needs at least one item with a name.",
  "errors": [
    "customer.email must be a valid email address.",
    "order.date is in the past.",
    "order.items needs at least one item with a name."
  ]
}

Base URL https://api.anyonein.co.uk/v1 is a placeholder until the production domain is confirmed. Found a mistake? Tell us.

#Request body

#customer

#order

#channels

#brand

#What happens next

#Validation errors

Request body

customer

order

channels

brand

What happens next

Validation errors