Developer

Automation API

These are the endpoints our Zapier app runs on. You can call them from your own scripts too: read leads, escalations and agent-attributed orders, create leads, add training rules, and subscribe to events.

Authentication

Send an API token as a bearer token. Each token belongs to one agent, so you never pass an agent id.

curl https://agentmatica.com/api/v1/me \
  -H "Authorization: Bearer amk_live_…"

Base URL: https://agentmatica.com/api/v1. Requests and responses are JSON. A missing, wrong or revoked token returns 401.

GET /me

Returns the agent the token belongs to. Zapier uses it to test the connection.

{
  "bot_id": "00000000-0000-4000-8000-000000000001",
  "bot_name": "Store assistant",
  "store_name": "shop.example.com",
  "website_url": "https://shop.example.com"
}

Leads

GET /leads

Recent leads, newest first. limit takes 1 to 50 and defaults to 3. Add email to find leads by email address.

GET /api/v1/leads?email=sam@example.com&limit=1

[
  {
    "id": "6f1c2a54-0b7e-4d8e-9c1a-2f3b4c5d6e7f",
    "created_at": "2026-10-15T10:24:00.000Z",
    "name": "Sam Rivera",
    "email": "sam@example.com",
    "phone": null,
    "message": "Do you ship to Canada?",
    "conversation_id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "conversation_url": "https://agentmatica.com/dashboard/bots/…/live/…",
    "dashboard_url": "https://agentmatica.com/dashboard/bots/…/leads"
  }
]

When a shopper leaves only a phone number, email is null.

POST /leads

Creates a lead and sends the same alerts as a lead from chat, for whichever of email, push, Slack, your webhook and Zendesk you have on. Send email or phone, plus optional name and message. Returns 201 with the lead.

Leads created this way do not fire the lead.captured REST hook. A Zap can't trigger itself in a loop.

GET /escalations

Recently escalated conversations, newest first. The id is the conversation id. The reason and summary only exist at the moment of escalation, so this list returns them as null. Live hook events include both.

[
  {
    "id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "escalated_at": "2026-10-15T10:31:00.000Z",
    "conversation_id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "reason": "Shopper asked to speak to a person",
    "summary": "Order #1042 arrived damaged.",
    "conversation_url": "https://agentmatica.com/dashboard/bots/…/live/…"
  }
]

GET /orders

Orders your agent helped make, newest first, from Shopify or WooCommerce. DIRECT means the agent built the cart. ASSISTED means the order contains products it recommended.

[
  {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "created_at": "2026-10-15T11:02:00.000Z",
    "platform": "shopify",
    "shop_domain": "demo-store.myshopify.com",
    "order_id": "5551234567890",
    "order_name": "#1043",
    "attribution_type": "DIRECT",
    "attribution_reason": "agent_card",
    "attributed_revenue": 89,
    "order_total": 112.5,
    "item_count": 3,
    "currency": "USD",
    "conversation_id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "conversation_url": "https://agentmatica.com/dashboard/bots/…/live/…"
  }
]

order_total and item_count can be null on older orders.

POST /training-rules

Adds a training rule from a plain-language instruction of up to 2,000 characters. We compile it with the same checks as a dashboard save, and it goes live straight away.

{
  "instruction": "When someone asks about the trail harness, mention free returns.",
  "allow_conflicts": false
}

If the rule contradicts one you already have, the request fails with 409 and the conflict in error. Send "allow_conflicts": true to save it anyway. A successful call returns 201:

{
  "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "summary": "Mention free returns when shoppers ask about the trail harness.",
  "rule_count": 1,
  "rules": [ { "id": "…", "summary": "…", "rule_type": "MANDATORY_DISCLOSURE", "enabled": true } ],
  "conflicts": []
}

One instruction can become more than one rule. Rules added this way show an Added from Zapier badge in your training rules.

REST hooks

Instant triggers use REST hooks. Subscribe a URL to an event, and we POST each event to it as it happens.

POST /api/v1/hooks
{ "event": "lead.captured", "target_url": "https://hooks.zapier.com/hooks/standard/…" }

201 { "id": "b2c3d4e5-…", "event": "lead.captured" }

lead.captured: a shopper left contact details in chat. Same body as one item from GET /leads.
conversation.escalated: the agent handed a chat to your team. Same body as one item from GET /escalations.
order.attributed: we recorded an order the agent helped make. Same body as one item from GET /orders.

Remove a subscription with DELETE /api/v1/hooks/{id}. Target URLs must be https Zapier hook URLs, and each agent can hold up to 50 subscriptions. If your endpoint answers 410 Gone, we delete the subscription. Each delivery waits up to 5 seconds and is not retried. Revoking the token stops its subscriptions.

For your own endpoint, use the signed custom webhook instead.

Errors and limits

Errors come back as { "error": "…" } with a status code: 400 bad input, 401 token problem, 404 not found, 409 conflict or subscription cap, 422 the rule could not be compiled or saved, 429 rate limit, 503 not available yet.

Each token can make 120 requests a minute across these endpoints. A 429 carries X-RateLimit-* headers, so wait for the reset before you retry.