SIMCOAI API for customer systems

Connect SIMCOAI to the systems you already use

The SIMCOAI API lets approved customers sync orders, refund requests, bookings, escalations and website chat from their own server. It is designed for ecommerce, booking systems, CRMs, helpdesks, POS tools and custom business software that need customer operations in one dashboard.

Public and secret keys

Create keys in the dashboard API page. Public keys identify the integration. Secret keys authenticate it and are shown once. Keep secret keys only on trusted servers, never in client-side JavaScript, mobile apps, screenshots or shared spreadsheets. Use HTTPS, rotate keys after supplier changes, and give each integration the narrowest scope it needs.

POST https://api.simcoai.co.uk/v1/orders
Content-Type: application/json
X-SIMCOAI-Public-Key: pk_simco_live_...
X-SIMCOAI-Secret-Key: sk_simco_live_...

• Use the narrowest scope that works for the integration.
• Send an Idempotency-Key header when retrying creates so duplicate orders or refunds are not created by network retries.
• Sign sensitive server-to-server payloads with HMAC-SHA256 where your integration needs tamper evidence.
• Use different keys for production, staging and support tooling.
• Revoke keys immediately if they are copied into the wrong place.

Sync orders safely

Use external_id for your system ID and order_number for the customer-facing reference. SIMCOAI will update an existing matching order instead of creating duplicates when the same order is resent.

curl -X POST https://api.simcoai.co.uk/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-SIMCOAI-Public-Key: pk_simco_live_..." \
  -H "X-SIMCOAI-Secret-Key: sk_simco_live_..." \
  -d '{
    "external_id":"shop-1001",
    "order_number":"ORD-1001",
    "customer_name":"Alex Morgan",
    "customer_email":"alex@example.com",
    "status":"processing",
    "total_amount":"99.00",
    "currency":"GBP",
    "notes":"Synced from approved order system"
  }'

Create refund requests for review

Refund records can be created from your support desk, ecommerce system or website form. Sensitive or high-risk refunds remain reviewable in the SIMCOAI dashboard according to your configured rules.

curl -X POST https://api.simcoai.co.uk/v1/refunds \
  -H "Content-Type: application/json" \
  -H "X-SIMCOAI-Public-Key: pk_simco_live_..." \
  -H "X-SIMCOAI-Secret-Key: sk_simco_live_..." \
  -d '{
    "external_id":"refund-7781",
    "order_number":"ORD-1001",
    "customer_email":"alex@example.com",
    "amount":"29.00",
    "currency":"GBP",
    "reason":"Customer requested a policy review",
    "notes":"Imported from support form"
  }'

Protect server-to-server sync

For higher-risk integrations, sign the exact JSON payload with your server-side secret key and send the digest in X-SIMCOAI-Signature. Keep the signing step on your server and log request IDs so support can investigate a sync without exposing customer secrets.

const crypto = require('crypto');
const body = { order_number: 'ORD-1001', status: 'processing' };
const signature = crypto
  .createHmac('sha256', process.env.SIMCOAI_SECRET_KEY)
  .update(JSON.stringify(body))
  .digest('hex');

Dashboard API endpoint reference

These are the main authenticated endpoints behind the SIMCOAI dashboard. All responses use the same JSON envelope with success, data, message and requestId fields. Authenticate with Authorization: Bearer <token> or the secure SIMCOAI session cookies.

Receive signed workflow API messages

Instead of polling, let SIMCOAI push events to your systems. In Integrations → Workflow API messages add an HTTPS endpoint and choose the events to receive — wildcards like refund.*, booking.*, escalation.* and order.*, or specific events such as refund.approved or booking.confirmed.

• Signing secret is shown once. Copy it into your server when you create or rotate the endpoint — SIMCOAI never shows it again.
• Verify every delivery. Each request includes an X-SIMCOAI-Signature HMAC‑SHA256 header (over timestamp.rawJsonBody) plus X-SIMCOAI-Event, X-SIMCOAI-Delivery-ID and X-SIMCOAI-Timestamp. Reject anything that does not verify.
• Deliveries retry automatically on failure; the delivery log shows status, attempts, response code and last error, and you can retry a failed message.

Only act externally when told to. Execute a real refund, booking or charge in your systems only when payload.workflow.shouldExecuteExternalAction is true. When it is false the message is a notification — record it or open a review task, but do not move money. This keeps money‑moving actions under an explicit SIMCOAI decision.

Idempotency, retries and errors

• Use idempotency keys. Send your own external_id or order_number so safe retries never create duplicates on either side.
• Handle errors by status. 401 means a bad or revoked key; 402/403 means a plan or permission limit; 422 means invalid fields; 428 means an action needs acceptance or verification first; 429 means slow down and retry with backoff.
• Read the message, not the object. Every error response includes a human‑readable message (or error.message) explaining what to fix.
• Keep secrets server‑side. Never call the API or handle secret keys or signing secrets from a browser.

Compliance and data rules

Only send data your business is allowed to process in SIMCOAI. Do not send payment card numbers, passwords, unnecessary health details, private staff notes or customer information that is not needed for the workflow. API activity is logged for security, usage limits and support troubleshooting. Review your privacy notice, retention rules and processor agreements before connecting live customer systems.