Connect your platform to a CrewTAC agent.

1. 1

   You call us

   Your system sends work in and gets a result back. Synchronous, simplest to build, and where every integration starts.

   your form, widget or backend job→POST /v1/…

   Use when: You have a website form, a chat widget, a batch importer, or any place a business event already happens in your code.

2. 2

   We call you

   When an agent finishes, we push a signed event to an endpoint you own. Your systems stay in sync without polling.

   signed event→your app, queue or warehouse

   Use when: You want results in your data warehouse, your notification system, or a queue your own workers consume.

3. 3

   We act in your systems

   The agent reads from and writes to your CRM, help desk, email or calendar through an adapter. Every write is previewable and idempotent, and high-impact actions wait for a human.

   agent⇄your CRM, help desk, calendar

   Use when: The agent should do something — create the CRM contact, open the ticket, book the call — rather than just report what it decided.

Which do you need?

1. 1

   Connect and call once

   Get a key, submit one record, read the response. Everything runs against mock connectors, so nothing touches your production systems.

2. 2

   Send real inputs, keep mock outputs

   The agent scores and decides; the write still goes to a mock. Compare its decisions against what your team would have done. This is where you calibrate, and it costs nothing to get wrong.

3. 3

   Connect one real system

   Usually the CRM or help desk. Use preview_action to see exactly what would be written before enabling writes.

4. 4

   Turn on outbound webhooks

   Your systems now receive results as they happen.

5. 5

   Tune the human-in-the-loop gates

   Decide what the agent may do unattended. Defaults are conservative: anything reaching a customer waits for a person.

6. 6

   Go live

   Work through the pre-launch checklist, starting with a subset of traffic and a kill switch you control.

curl https://aiapp.crewtac.com/v1/leads \
  -H "X-API-Key: $CREWTAC_API_KEY"

Scopes

Request the narrowest set that does the job; a separate read-only key for reporting is good practice. A request missing a scope returns 403 permission_denied naming the scope it needed.

curl -X POST https://aiapp.crewtac.com/v1/leads \
  -H "X-API-Key: $CREWTAC_API_KEY" \
  -H "Idempotency-Key: 6f1c2a90-3e7d-4b1a-9c22-8f0e1d4a55b3" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "email": "...", "problem": "...",
        "consent_status": "granted" }'

The 409 is deliberate. Silently returning the old response would hide a bug in your code where one key is being reused for two different records. Idempotency also runs inside the connector layer, so even a request arriving without a key updates an existing CRM contact rather than creating a second one.

The error envelope

Branch on code, never on message — message text is written for humans and may be reworded without notice.

{
  "error": {
    "code": "validation_error",
    "message": "Human-readable explanation.",
    "retryable": false,
    "details": {},
    "correlation_id": "corr_9f2c1a0b4e7d"
  }
}

Retry retryable failures with exponential backoff and jitter, reusing the same Idempotency-Key. Never retry a non-retryable error — the same request will fail identically. Every response carries X-Correlation-ID; send your own to trace a request across both systems, and include it in any support conversation.

{
  "name": "Sofia Alvarez",
  "email": "sofia@brightpath.example",
  "company": "Brightpath SaaS",
  "role": "VP RevOps",
  "company_size": "51-200",
  "industry": "SaaS",
  "source": "demo_request",
  "consent_status": "granted",
  "problem": "Inbound leads sit in a queue for two days...",
  "crm_context": { "existing_account_id": "0015g00000XyZ" }
}

{
  "lead": {
    "id": "lead_f546425682d44ccc94a24880",
    "status": "qualified",
    "external_ids": { "crm_contact_id": "cont_7a1e0b93c4d24f18" }
  },
  "qualification": {
    "score": 82,
    "fit": "high",
    "intent": "buying",
    "confidence": 0.648,
    "reason_codes": [
      { "code": "COMPANY_SIZE",    "label": "Company size 51-200.",         "points": 12 },
      { "code": "TARGET_INDUSTRY", "label": "'SaaS' is a target industry.", "points": 6  },
      { "code": "SENIOR_ROLE",     "label": "Decision-maker role.",         "points": 9  },
      { "code": "INTENT",          "label": "Classified intent: buying.",   "points": 18 }
    ],
    "rules_version": "v1",
    "prompt_version": "sales.lead_classify@v1",
    "model_version": "claude-opus-5"
  },
  "actions": [
    {
      "action_type": "book_discovery_call",
      "status": "pending_approval",
      "requires_approval": true,
      "approval_reason": "High-impact outbound action requires human approval."
    }
  ],
  "duplicate": { "found": false, "source": "none", "confidence": "none" }
}

Actions and the approval gate

An action with pending_approval is waiting for a person. Nothing was sent.

Approving accepts an override_action_type that replaces the agent’s recommendation. The original is preserved in the audit trail, so the agent’s judgement stays visible and reviewable.

Ingest your documentation first

With an empty knowledge base the agent escalates everything — correctly, but uselessly.

POST /v1/knowledge/documents

{
  "title": "Billing and Payments",
  "content": "# Billing and Payments\n\n## Refunds\nRefunds are...",
  "source_uri": "https://yourdocs.example/kb/billing",
  "metadata": { "product": "northbeam", "audience": "customer" }
}

An answered question

{
  "reply": {
    "status": "delivered",
    "text": "Refunds are available within 14 days of a charge...",
    "confidence": 0.726,
    "retrieval_count": 3,
    "top_score": 0.31,
    "source_refs": [
      {
        "document_title": "Billing and Payments",
        "document_version": 1,
        "heading_path": "Billing and Payments > Refunds",
        "citation": "Billing and Payments v1 - Refunds",
        "score": 0.31
      }
    ],
    "escalated": false,
    "prompt_version": "support.grounded_answer@v1"
  },
  "ticket": null,
  "escalated": false
}

source_refs names the exact document version used. Show it to the customer or keep it for supervisor review — but store it either way, because it is what makes the answer checkable later. An escalation carries no citations: nothing was asserted, so there is nothing to cite.

Escalation codes

Submitting a document

multipart/form-data, not JSON — the file is the body. Send document_type when you already know it; leave it out and the agent classifies the document itself.

curl -X POST https://aiapp.crewtac.com/v1/documents \
  -H "X-API-Key: $CREWTAC_API_KEY" \
  -H "Idempotency-Key: 7c1f2b40-9a55-4e01-b7d3-2c8e5f1a9042" \
  -F "file=@invoice-2041.pdf" \
  -F "document_type=invoice"

The response

One call runs the whole workflow, so you get the finished result rather than a job id.

{
  "document": {
    "id": "doc_8c1c5ca9ed944c20b26a",
    "status": "needs_review",
    "document_type": "invoice",
    "classification_confidence": 0.94,
    "text_method": "pdf_text_layer",
    "checksum": "3f9a..."
  },
  "extraction": {
    "overall_confidence": 0.91,
    "schema_id": "invoice",
    "schema_version": "v1",
    "rules_version": "v1",
    "prompt_version": "document.extract@v1",
    "document_errors": []
  },
  "fields": [
    {
      "field_name": "total_amount",
      "value": 1440.0,
      "raw_value": "1,440.00",
      "confidence": 0.93,
      "validation_status": "valid",
      "evidence": "Total Due:       1,440.00",
      "high_risk": true
    }
  ],
  "review_task": {
    "reason": "High-risk fields always require human confirmation.",
    "reason_codes": ["HIGH_RISK_FIELD"],
    "fields_to_check": ["subtotal", "tax_amount", "total_amount"]
  }
}

Read value for the normalised value and raw_value for the text as printed. evidence is the line it was read from — show it to your reviewers, because it is the difference between checking a value in seconds and hunting for it.

Document types you define

A type is a configuration file, not a development ticket. You decide which fields exist, what makes a value valid, what the arithmetic should come to, and which fields always need a person.

id: invoice
version: v1

fields:
  - name: total_amount
    type: number
    required: true
    high_risk: true            # always reviewed, whatever the confidence
    minimum: 0
    aliases: ["Total Due", "Amount Due", "Balance Due"]

cross_field_rules:
  - rule: sum_equals
    fields: [subtotal, tax_amount]
    target: total_amount
    message: "Subtotal plus tax must equal the total."

aliases are the labels a real document prints — an invoice says “VAT”, not tax_amount. Every result records the schema, prompt, rules and model version that produced it, so an extraction from last quarter can still be read against the definition in force at the time.

Why a document reaches the review queue

What your system receives

Only an approved document exports. Your fields are under data; everything else is provenance. Dates arrive as ISO-8601 and money as numbers with the presentation stripped.

{
  "source_document_id": "doc_8c1c5ca9ed944c20b26a",
  "document_type": "invoice",
  "schema_version": "invoice@v1",
  "filename": "invoice-2041.pdf",
  "checksum": "3f9a...",
  "data": {
    "invoice_number": "INV-2041",
    "total_amount": 1440.0,
    "issue_date": "2026-08-14",
    "currency": "GBP"
  }
}

Starting a workflow

request_text is what a person wrote. context is the structured data the steps bind their arguments from — keep them separate, because a tool argument is never interpolated from raw request prose. Set workflow_id to skip classification when you already know the process.

{
  "request_text": "We have a new starter joining next month, please onboard them.",
  "requester": "hr@yourcompany.example",
  "context": {
    "person_name": "Jo Example",
    "person_email": "jo@yourcompany.example",
    "start_date": "2026-10-01",
    "role": "Operations Analyst"
  }
}

{
  "task": {
    "id": "task_5f4c...",
    "workflow_id": "employee_onboarding",
    "workflow_version": "v1",
    "routing_confidence": 0.95,
    "routing_signals": ["new starter", "onboard"],
    "status": "awaiting_approval",
    "current_step": 2,
    "missing_fields": []
  },
  "plan": [
    { "id": "raise_it_ticket",    "tool": "ticketing.create_ticket", "requires_approval": false },
    { "id": "create_crm_contact", "tool": "crm.create_contact",      "requires_approval": false },
    { "id": "welcome_email",      "tool": "internal.notify_requester", "requires_approval": true }
  ],
  "executions": [
    {
      "step_id": "raise_it_ticket",
      "status": "succeeded",
      "external_id": "TKT-FA22844D",
      "input_payload": { "subject": "Onboarding: Jo Example", "priority": "normal" }
    }
  ],
  "pending_approval": {
    "step_id": "welcome_email",
    "preview": { "payload": { "to": "jo@yourcompany.example",
                              "subject": "Welcome — your first day" } }
  },
  "detail": "New starter onboarding is paused at 'welcome_email' for human approval."
}

plan comes from the workflow definition, so you can see the whole sequence — including which steps will stop — before any of it runs.

Workflows you control

$name binds from the task’s context. A bare $name keeps the value’s type; inside a sentence it is interpolated as text.

id: expense_approval
version: v1
name: Expense approval
intent_hints: ["expense", "reimburse", "out of pocket"]

required_fields:
  - name: amount              # no amount, no workflow run

steps:
  - id: open_case
    tool: ticketing.create_ticket
    arguments:
      subject: "Expense claim: $amount"
      requester: $requester

  - id: tell_them
    tool: internal.notify_requester
    requires_approval: true   # this one reaches a person
    arguments:
      to: $requester
      subject: "Your expense claim"

Bad configuration fails when the file loads, not half way through a live run — a workflow with no steps, a duplicate step id, or a step naming a tool that is not registered is refused outright. A workflow that routes correctly and dies on step three has already raised a ticket and emailed a customer.

What the agent cannot do

Asking a question

user_identity and role are how the agent respects your CRM’s permissions — they drive both which records are retrieved and which fields are readable.

{
  "question": "Tell me about Northwind Supplies Ltd",
  "user_identity": "rep@yourcompany.example",
  "role": "sales_rep"
}

{
  "answered": true,
  "answer": "Northwind Supplies Ltd is active, renewing 2026-11-30.",
  "record_refs": ["ACC-1001"],
  "records": [
    {
      "external_id": "ACC-1001",
      "kind": "account",
      "fields": { "name": "Northwind Supplies Ltd", "status": "active",
                  "annual_value": 48000.0, "renewal_date": "2026-11-30" },
      "hidden_fields": []
    }
  ],
  "intent": "account_summary",
  "structured_query": {
    "intent": "account_summary",
    "account_ref": "Northwind Supplies Ltd",
    "filters": { "owner": "rep@yourcompany.example" },
    "limit": 10
  },
  "confidence": 0.85,
  "follow_ups": ["Northwind Supplies Ltd renews on 2026-11-30."]
}

record_refs are your CRM’s own ids. Show them — they are what makes the answer checkable, and an answer that cites nothing is refused rather than shown. Note the owner filter in structured_query: it was added by the role, not by the question, and no phrasing removes it.

Roles you map onto your own

Permissions narrow the query as it is built, so a record the user may not see is never loaded — it cannot surface through a count, a summary, or an error that names it. hidden_fields names what a role could not read, because silently trimming a response makes an incomplete answer look like a complete one.

When it refuses

Preview, then execute

A preview writes nothing and returns the token execute requires. A role that may not perform the action is refused here, so no token is ever issued for something that could not run.

{
  "action_request_id": "acrq_...",
  "description": "Create a task 'Chase the renewal pack'.",
  "payload": { "subject": "Chase the renewal pack",
               "owner": "rep@yourcompany.example" },
  "will_create": true,
  "is_reversible": true,
  "warnings": [],
  "approval_token": "apt_...",
  "expires_at": "2026-09-08T09:12:00Z",
  "detail": "Nothing was written. Approve with this token to execute."
}

{
  "action_request_id": "acrq_...",
  "approval_token": "apt_...",
  "approved_by": "manager@yourcompany.example"
}

{
  "schema_version": "1.0",
  "event_type": "qualification.completed",
  "tenant_id": "your_tenant_id",
  "correlation_id": "corr_9f2c1a0b4e7d",
  "occurred_at": "2026-09-04T10:15:02.441Z",
  "data": { }
}

import hashlib, hmac, time

TOLERANCE_SECONDS = 300

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    timestamp, provided = parts.get("t"), parts.get("v1")
    if not timestamp or not provided:
        return False

    # Reject old signatures so a captured request cannot be replayed.
    if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()

    # Constant-time compare - a plain == leaks the digest through timing.
    return hmac.compare_digest(expected, provided)

Events we send you

More events arrive as agents ship. Ignore event types you do not recognise rather than erroring — that is what lets us add them without breaking you.

Delivery semantics

Events you send us

class Connector(ABC):
    name: str
    kind: ConnectorKind          # crm | ticketing | email | calendar
                                 # storage | rest | project_management

    def authenticate(self) -> bool: ...
    def health_check(self) -> dict: ...
    def read(self, ctx, *, resource, params=None) -> list[dict]: ...
    def preview_action(self, ctx, *, action, payload) -> ActionPreview: ...
    def execute_action(self, ctx, *, action, payload,
                       idempotency_key=None) -> ActionResult: ...
    def handle_webhook(self, ctx, *, event_type, payload) -> dict: ...

The two methods that matter

What a connector must do

Testing your connector

If you would rather not write code

The second option is often the right first step: value flows in days, and the connector decision waits until you know which writes you actually want automated.

Requesting another tenant’s record ID returns 404, not 403 — we do not confirm that an ID exists in a tenant you cannot see.

Never stored

Model providers and your data

Guardrails you can rely on

The first two weeks

Expect to tune. Nothing below indicates a broken system — and the override and escalation audit trails are your tuning data. Read them weekly for the first month.