> ## Documentation Index
> Fetch the complete documentation index at: https://docs.irisagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://web.irisagent.com/).
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**.

<Note>
  Credential values are stored securely and cannot be viewed after saving. Store them in a safe location before saving.
</Note>

***

## 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:**

```text theme={null}
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:

```text theme={null}
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`:

```text theme={null}
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}}`.

<Note>
  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.
</Note>

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:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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](/configuring-ai-and-automation/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](https://web.irisagent.com/triggers).
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](mailto:contact@irisagent.com) if you encounter any issues or need help setting up your Custom API integration.