Custom APIs

A Custom API connects IrisAgent to any HTTP endpoint (internal systems, third-party services, data warehouses). You can use it:

In AI FAQ workflows: IrisAgent collects the required fields from the customer, calls your API, and explains the response in plain language.
As a trigger condition: for example, “only run this automation if the customer is on the Premium plan.”

To create a Zendesk ticket from a procedure, use the built-in Create Zendesk ticket action. You only need a Custom API for a different payload, such as mapping values to Zendesk custom ticket fields.

Step 1: Open the Custom APIs configuration

In the IrisAgent dashboard, go to Data Sources → APIs.
On the Custom APIs card, click Configure.

A side panel opens with two tabs: APIs and Credentials.

Step 2: Add a credential (optional)

Skip this if your API needs no authentication or uses a token in the URL.

Open the Credentials tab and click Add Credential.
Fill in:
Field Example
Credential Name Production Bearer Token
Header Name Authorization or X-API-Key
Header Value Bearer sk-abc123
Click Create Credential.

Field	Example
Credential Name	`Production Bearer Token`
Header Name	`Authorization` or `X-API-Key`
Header Value	`Bearer sk-abc123`

You can also create a credential from inside the API form (Create New Credential, then Create & Select).

You cannot view a credential value after saving. Keep a copy somewhere safe.

Step 3: Create a Custom API

On the APIs tab, click Add API and fill in the Create Custom API form.

Field	Description
Name	Shown in the trigger builder, e.g. `Customer Premium Check API`
API Credential	A credential from Step 2, or None
Method	`GET`, `POST`, `PUT`, or `DELETE`
URL	Full endpoint URL. Supports template variables
Headers	Extra key/value headers beyond the credential
Request Body	For `POST` and `PUT`. Supports template variables

Template variables

Use {{variableName}} in the URL, headers, or body. IrisAgent fills them in before each call. Built-in variables: {{ticketId}}, {{priority}}, {{status}}, {{subject}}, {{accountId}} (the account or company ID on the ticket).

https://api.yourcompany.com/customers/check?ticketId={{ticketId}}&accountId={{accountId}}

Any other name is a custom variable. In FAQ workflows, IrisAgent collects it from the customer before calling the API:

https://api.yourcompany.com/orders/{{orderId}}

Response schema

Click Add Field for each response value you want to use. Set the Field name (the JSON key, e.g. isPremium) and Field type (String, Boolean, Integer, or Float). For {"isPremium": true, "tier": "enterprise"}, add isPremium (Boolean) and tier (String).

Expression

The expression evaluates the response. Reference fields as response.fieldName:

response.isPremium == true && response.tier == "enterprise"

Set Return Type to what the expression returns (String, Boolean, Integer, or Float).

Prerequisite (optional): run another API first

Use this to feed one API’s result into another call. For example, HubSpot needs a contact’s record ID before you can link it to a ticket.

Field	Description
Run this action first	Another Custom API to run first. Leave as None to disable
Store its result as	A variable name (letters, numbers, underscores). Use it as `{{yourName}}` in this API’s URL, headers, and body

The injected value is the prerequisite API’s Expression result, so make that expression return the single value you need (for example, the new record’s id). An API cannot be its own prerequisite. Click Create API to save.

Step 4: Test your API

Testing is available after you save.

Click the edit icon next to your API.
In the Test API Configuration section, enter sample values for each variable.
Click Run Test.

You see the expression result, the execution time, and any error. Adjust the URL, schema, or expression until the result is correct.

Example: link a HubSpot contact to a new ticket

HubSpot only shows a contact on a ticket if the ticket is created with an association to the contact’s record ID. Chain two APIs to do this.

API 1: Upsert HubSpot contact

Creates the contact or returns the existing one, and outputs its ID.

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

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

{{email}} and {{name}} are custom variables collected from the customer.

API 2: Create HubSpot ticket

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

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 } ]
    }
  ]
}

On handoff, IrisAgent upserts the contact, stores its ID as {{contactId}}, and creates the ticket linked to it.

Use Custom APIs in workflows

In AI FAQ workflows (recommended)

See Using Custom APIs in plain-English workflows.

As a case trigger condition

Go to Automate → Case Triggers.
Click Create New Trigger and add a condition.
In the condition picker, select your API. It is listed as API: <name>.
Enter the value to compare against (for example, true for a Boolean).
Save the trigger.

When a ticket arrives, IrisAgent calls your API with the ticket’s context and runs the trigger actions only if the condition matches. You can combine API conditions with other conditions. The response schema fields are also available in the Auto-respond to customer and Create Private Note actions. Insert them with the field picker. Need help? Email us.

Get started

Connect your data

Customer-facing AI agents

Agent Assist

Internal AI agents

IrisAgent Helpdesk

Ticket automation

AI answers and knowledge

Insights and quality

Admin and security

Step 1: Open the Custom APIs configuration

Step 2: Add a credential (optional)

Step 3: Create a Custom API

Template variables

Response schema

Expression

Prerequisite (optional): run another API first

Step 4: Test your API

Example: link a HubSpot contact to a new ticket

API 1: Upsert HubSpot contact

API 2: Create HubSpot ticket

Use Custom APIs in workflows

In AI FAQ workflows (recommended)

As a case trigger condition

​Step 1: Open the Custom APIs configuration

​Step 2: Add a credential (optional)

​Step 3: Create a Custom API

​Template variables

​Response schema

​Expression

​Prerequisite (optional): run another API first

​Step 4: Test your API

​Example: link a HubSpot contact to a new ticket

​API 1: Upsert HubSpot contact

​API 2: Create HubSpot ticket

​Use Custom APIs in workflows

​In AI FAQ workflows (recommended)

​As a case trigger condition

Step 1: Open the Custom APIs configuration

Step 2: Add a credential (optional)

Step 3: Create a Custom API

Template variables

Response schema

Expression

Prerequisite (optional): run another API first

Step 4: Test your API

Example: link a HubSpot contact to a new ticket

API 1: Upsert HubSpot contact

API 2: Create HubSpot ticket

Use Custom APIs in workflows

In AI FAQ workflows (recommended)

As a case trigger condition