Custom API Integrations — Connecting Your Agent to Any System

If your business uses a tool that isn't in the pre-built integration list, you can connect it as a custom integration. Any system with an HTTP API can become a tool your agent uses during calls.

Custom API tools are managed at API Tools in the dashboard sidebar (/dashboard/tools). Each tool gets a full-page editor where you define what it does, what data it needs, and how to reach your API — plus a built-in test panel.

What Custom Integrations Can Do

Custom integrations are HTTP requests your agent can make during a conversation:

• Look up information — check inventory, verify insurance eligibility, find customer records
• Create records — book appointments in your PMS, create leads in your CRM, submit service requests
• Update records — modify bookings, update customer preferences, change appointment status
• Notify external systems — send webhooks to trigger workflows, alert staff, update dashboards

How They Work

Each custom integration is defined with:

• Name and description — what the tool does (helps the agent decide when to use it)
• HTTP method — GET, POST, PUT, PATCH, DELETE
• URL template — the API endpoint, with optional parameter placeholders
• Parameters — what data the agent collects from the caller and passes to the API
• Authentication — API key, bearer token, or OAuth credentials
• Response mapping — how to extract the useful information from the API response

During a call, when the agent decides it needs to use a custom integration, it:

1. Collects the required parameters from the conversation
2. Builds the HTTP request
3. Sends it to your API
4. Reads the response
5. Continues the conversation with the results

Building a Tool from an Example

The fastest way to define parameters is pasting an example. On a new tool, the parameters section starts with a paste box: drop in the JSON body your API expects (most API docs include one) and the full parameter list builds itself — field names, types, and nesting, including lists of structured items like an order's line items. You then add a short guidance note to each field telling the agent what it is and how to collect it.

For structured fields, the same shortcut is available in place: open a "List of objects" or "Object" field's details and use Paste a sample element to define its fields from one example element. Re-pasting an updated example never erases your guidance; it only updates the structure.

As you build, the request preview shows exactly what the agent will send — method, URL, and an example JSON body — so you can compare it against your API documentation at a glance.

Value Lists (Allowed Values)

Any field can carry a list of allowed values. With a value list set, the agent can only pass one of those exact values — anything else is refused before it reaches your API, and the agent is told the allowed options so it can ask the caller to pick. Use this for fields like status codes, service types, or equipment categories where your API accepts a fixed set.

If you want to suggest common values while still allowing free input, list them in the field's guidance text instead of the value list.

Context Burden Levels

Each integration has a context burden level that controls how the agent decides to use it:

• Ambient — the agent uses it automatically in the background, without mentioning it to the caller
• Conversational — the agent uses it naturally as part of the conversation ("Let me check that for you")
• Requested — the agent only uses it when the caller explicitly asks ("Can you look up my account?")
• Confirmed — the agent asks for confirmation before using it ("I can book that for you — shall I go ahead?")
• Verified — the agent requires identity verification before using it (for sensitive operations)

This gives you fine-grained control over when and how your agent interacts with external systems.

Authentication

Custom integrations support multiple auth methods:

• API Key — passed as a header or query parameter
• Bearer Token — passed in the Authorization header
• OAuth — for integrations that require user-level authorization

Credentials are encrypted with AES-256-GCM and stored securely. They are never exposed in logs, transcripts, or the dashboard.

Correlation Headers

Every outbound HTTP request from a custom integration includes three correlation headers so your endpoint can tie the request back to the call that triggered it:

These are added by Allison automatically — no configuration required, no per-integration parameter setup. If your endpoint cares about the call context (writing breadcrumbs, correlating with your own call log, joining post-call webhook events), read these headers; if it doesn't, ignore them.

On live calls, X-Allison-Org-ID and X-Allison-Tool-Key are always present; X-Allison-Call-ID is sent unless the rare bridge-edge case where the call hasn't been bound yet. Dashboard test invocations (the tool page's test panel) send none of the three headers — they're not tied to a real call. Receivers should treat all three as optional and fall back gracefully when absent.

Testing

Every tool's editor page has a built-in test panel. You can send a real request with sample parameters (fields with value lists become dropdowns) and see the full request/response — status code, body, and latency. This lets you verify the tool works before your agent tries to use it on a live call.