Custom APIs

Connect any external HTTP API to IrisAgent so it can fetch live data and use it as a trigger condition or AI workflow step

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:

   Field	Description
   Credential Name	A human-readable label, e.g. Production Bearer Token
   Header Name	The HTTP header to send, e.g. Authorization or X-API-Key
   Header Value	The 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

Field	Description
Name	A descriptive name shown in the trigger builder, e.g. Customer Premium Check API
API Credential	Select a credential from Step 2, or leave as None for unauthenticated requests

HTTP configuration

Field	Description
Method	GET, POST, PUT, or DELETE
URL	The full endpoint URL. Supports template variables (see below)
Headers	Any additional headers beyond the credential. Add as many key/value rows as needed
Request Body	Available 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):

Variable	Value 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).

Prerequisite (optional): run another API first

Some workflows need to call one API and then feed its result into a second call. A common case: HubSpot requires a contact’s record ID to link it to a ticket, so you have to create or look up the contact before creating the ticket.

The Prerequisite section, at the bottom of the form, lets this Custom API run another Custom API first and reuse its result:

Field	Description
Run this action first	Select another Custom API to run before this one. Its Expression result is captured. Leave as None to disable chaining
Store its result as	A variable name (letters, numbers, and underscores). The prerequisite’s result becomes available to this API as {{yourName}} in the URL, headers, and body

At call time IrisAgent runs the prerequisite first, evaluates its Expression, and injects the value under the name you chose. You then reference it like any other template variable, for example {{contactId}}.

The injected value comes from the prerequisite API’s own Expression, so make sure that API’s Expression returns the single value you want (for example, the new record’s id). The prerequisite dropdown never lists the API you are currently editing, so an API cannot depend on itself.

3. 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.

---

Example: chain two APIs to link a HubSpot Contact to a ticket

When a chatbot handoff creates a HubSpot ticket, HubSpot will not automatically link the person to it just because their email appears in the ticket text. To show up under the ticket’s Contacts panel, the ticket has to be created with an association to the contact’s record ID. That takes two calls: first resolve the contact, then create the ticket linked to it. Use a Prerequisite to chain them.

API 1: Upsert HubSpot contact

This creates the contact if it is new, or returns the existing one, and outputs its ID.

Field	Value
Name	Upsert Hubspot contact
API Credential	Your HubSpot credential (the private app token must include the crm.objects.contacts.write scope)
Method	POST
URL	https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert
Request Body	see below
Expression	response.results[0].id
Return Type	String

Request body:

{
  "inputs": [
    {
      "idProperty": "email",
      "id": "{{email}}",
      "properties": { "email": "{{email}}", "firstname": "{{name}}" }
    }
  ]
}

{{email}} and {{name}} are custom variables IrisAgent collects from the customer during the conversation.

API 2: Create HubSpot ticket

This creates the ticket and links it to the contact from API 1.

Field	Value
Name	Create Hubspot ticket
Method	POST
URL	https://api.hubapi.com/crm/v3/objects/tickets
Request Body	see below
Prerequisite → Run this action first	Upsert Hubspot contact
Prerequisite → Store its result as	contactId

Request body (the associations block references {{contactId}} from the prerequisite; association type ID 16 is HubSpot’s Ticket-to-Contact type):

{
  "properties": {
    "subject": "Support: {{issue}}",
    "content": "Issue: {{issue}}\nName: {{name}}\nEmail: {{email}}"
  },
  "associations": [
    {
      "to": { "id": "{{contactId}}" },
      "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 16 } ]
    }
  ]
}

Now when the handoff runs, IrisAgent upserts the contact, captures its ID as {{contactId}}, and creates the ticket already linked to that contact.

---

Using Custom APIs in Workflows

[Recommended] As a live data source in AI FAQ workflows for chats and cases

See Workflows — Using Custom APIs in plain-English workflows for how to wire a Custom API into an AI-driven multi-turn conversation.

As a trigger condition (drag-and-drop builder) for cases

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.

---

Feel free to email us if you encounter any issues or need help setting up your Custom API integration.