SIMCOAI API
A small REST API for keeping your own systems in step with the work SIMCOAI captures: orders, refunds, bookings, escalations and the customers they all belong to.
Everything lives under one base
All public endpoints are versioned and served over HTTPS. Plain HTTP is not accepted.
https://api.simcoai.co.uk/v1Requests are authenticated with an API key. Responses always use the same envelope, so a single client wrapper can handle every endpoint.
The complete public surface
This is the entire public API. There is nothing hidden behind it.
/v1/meConfirm which account and scopes a key belongs to.
Requires scope read
/v1/signature-exampleReturn a worked HMAC example so you can validate your signing code.
Requires scope read
/v1/chatSend a customer message to the AI and receive a reply.
Requires scope chat:write
/v1/{table}List records for orders, refunds, bookings, escalations or customers.
Requires scope read
/v1/{table}Create or upsert a record.
Requires scope write
/v1/{table}/{id}Fetch a single record.
Requires scope read
/v1/{table}/{id}Update a single record.
Requires scope write
Five tables
The {table} segment accepts exactly five values. Anything else returns an error telling you which are valid.
| Table | Purpose | Workflow-backed |
|---|---|---|
orders | Order records the AI can look up on a call | No |
refunds | Refund requests captured from calls or chat | Yes |
bookings | Appointment requests | Yes |
escalations | Requests routed to a person | Yes |
customers | One record per person, with the orders, refunds, bookings and escalations linked to them | No |
POST /v1/customers is an upsert, not a plain create: a customer is matched on their email address or the significant digits of their phone number, so replaying your customer list does not create a second record for somebody already on file, and a blank value you send never overwrites one already stored. customers uses its own customers:read and customers:write scopes rather than the general read and write ones, so an integration that only files refunds is not also handed your contact list.
Workflow-backed tables carry verification state and human review. Creating one through the API does not approve it — see verification codes.
Every response has the same shape
Success and failure differ only in success and which of data/details is populated.
{
"success": true,
"data": { },
"message": "Order loaded.",
"requestId": "req_h9afi6vi",
"timestamp": "2026-07-31T16:04:11.000Z"
}Always read success rather than inferring from the HTTP status alone, and log requestId — it is what support will ask for.
Where to go next
- Authentication — keys, scopes and how to send them
- Errors — every code and what to do about it
- Rate limits — windows and how to back off
- Idempotency — safe retries and duplicate prevention
- cURL examples and Node.js examples