Skip to main content

​
Overview

Custom APIs let you connect IrisAgent to any external HTTP endpoint — your internal systems, third-party services, or data warehouses. Once configured, a Custom API can be used in two ways:
  • As a trigger condition in the drag-and-drop Workflows builder (e.g., “only run this automation if the customer is on the Premium plan”)
  • As a live data source in AI-powered FAQ workflows, where IrisAgent collects required fields from the customer, calls your API, and presents the response in natural language

​
Step 1: Open the Custom APIs configuration

  1. Log in to the IrisAgent dashboard.
  2. Click on Data Sources in the left navigation.
  3. Scroll to the Development section and click Configure on the Custom APIs card.
This opens a side panel with two tabs: APIs and Credentials.

​
Step 2: Add a credential (if your API requires authentication)

Skip this step if your API is publicly accessible or uses URL-based tokens.
  1. In the side panel, click the Credentials tab.
  2. Click Add Credential.
  3. Fill in the fields:
    FieldDescription
    Credential NameA human-readable label, e.g. Production Bearer Token
    Header NameThe HTTP header to send, e.g. Authorization or X-API-Key
    Header ValueThe secret value, e.g. Bearer sk-abc123
  4. Click Create & Select.
Credential values are stored securely and cannot be viewed after saving. Store them in a safe location before saving.

​
Step 3: Create a Custom API

  1. Click the APIs tab and then Add API.
  2. Fill in the Create Custom API form:

​
Basic information

FieldDescription
NameA descriptive name shown in the trigger builder, e.g. Customer Premium Check API
API CredentialSelect a credential from Step 2, or leave as None for unauthenticated requests

​
HTTP configuration

FieldDescription
MethodGET, POST, PUT, or DELETE
URLThe full endpoint URL. Supports template variables (see below)
HeadersAny additional headers beyond the credential. Add as many key/value rows as needed
Request BodyAvailable for POST and PUT methods. Supports template variables

​
Template variables

Use {{variableName}} placeholders in the URL, headers, or body to inject live ticket context at call time. IrisAgent automatically substitutes these before making the request. Built-in variables (always available):
VariableValue injected
{{ticketId}}The unique identifier of the ticket
{{priority}}The priority level of the ticket
{{status}}The current status of the ticket
{{subject}}The subject line of the ticket
{{accountId}}The account/company ID associated with the ticket
Example URL using a built-in variable: 
https://api.yourcompany.com/customers/check?ticketId={{ticketId}}&accountId={{accountId}}
Custom variables — for FAQ workflows that collect information from the customer (such as an order number or email address), you can define your own placeholder names: 
https://api.yourcompany.com/orders/{{orderId}}
IrisAgent will automatically detect {{orderId}} as a field it needs to collect from the customer before calling the API.

​
Response schema

Define the fields you expect back from your API. This tells IrisAgent how to interpret the response.
  1. Click Add Field.
  2. For each field, set:
    • Field name — matches the JSON key in the response, e.g. isPremium
    • Field type — String, Boolean, Integer, or Float
  3. Add one field per value you want to use in an expression or surface to the customer.
Example — for a response like {"isPremium": true, "tier": "enterprise"}:
  • Field isPremium → Boolean
  • Field tier → String

​
Expression

Write a condition that evaluates the API response. IrisAgent uses this expression to determine the trigger result. Access response fields using response.fieldName: 
response.isPremium == true && response.tier == "enterprise"
Set the Return Type to match what your expression evaluates to (Boolean, String, Integer, or Float).
  1. Click Create API to save.

​
Step 4: Test your API

After saving, reopen the API in edit mode to use the built-in test tool.
  1. Click the edit icon next to your API in the table.
  2. Expand the Test API section.
  3. Enter sample values for each template variable (built-in and custom).
  4. Click Run Test.
IrisAgent will call your API with the provided values and show:
  • The expression result
  • The execution time in milliseconds
  • Any error message if the call failed
Iterate on the URL, expression, or schema until the test returns the expected result.

​
Using Custom APIs in Workflows

​
As a trigger condition (drag-and-drop builder)

  1. Go to Automations → Triggers on the IrisAgent dashboard.
  2. Click + Create New Trigger and add a Condition.
  3. In the condition picker, scroll to the API section — your Custom APIs appear listed as API: <name>.
  4. Select your API. Depending on its return type, you will be prompted to enter a comparison value (e.g. true for a Boolean, or a string to match).
  5. Save and activate the trigger.
When a ticket arrives, IrisAgent automatically calls your API with the ticket’s context, evaluates the expression, and runs the trigger actions only if the condition is met.

​
As a live data source in AI FAQ workflows

See Workflows — Using Custom APIs in plain-English workflows for how to wire a Custom API into an AI-driven multi-turn conversation.
Feel free to email us if you encounter any issues or need help setting up your Custom API integration.