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 agent instructions: what the tool does and when to use it. Every word of the instructions is given to the agent, so write them as directions, not a summary
• 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: none, API key, bearer token, or basic auth

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 is instructed to verify the caller's identity 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:

• None: for endpoints that don't need credentials
• API Key: sent in a header you name (defaults to X-API-Key)
• Bearer Token: passed in the Authorization header
• Basic Auth: username and password

Credentials are encrypted at rest. They are never exposed in logs, transcripts, or the dashboard.

Correlation Headers

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

These are added by Allison automatically, with 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, texting the caller back), read these headers; if it doesn't, ignore them. A header value you configure yourself under any of these names is replaced on live calls; they always carry Allison's value.

On live calls, X-Allison-Org-ID and X-Allison-Tool-Key are always present; X-Allison-Call-ID and X-Allison-Caller-Number may be absent in rare cases. Dashboard test invocations (the tool page's test panel) send none of these headers, since they are not tied to a real call. Receivers should treat all four 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.