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

# Custom API

> Learn how to configure Custom APIs to allow your Assistant to fetch, send, and update data dynamically before, during or after the call.

By connecting a Custom API, your assistant can interact with external systems to retrieve customer data, log information, or trigger actions based on natural language conditions.

<Steps>
  <Step title="Navigate to the Custom API Tool">
    1. Select **Assistants** from the left navigation panel.
    2. Choose the specific assistant you want to configure.
    3. Go to the **Tools** tab.
    4. Select **Custom API**.

    <Frame>
      <img src="https://mintcdn.com/superdash/fa4KzVNLE_4mSQ2J/images/catalyst-custom-api.png?fit=max&auto=format&n=fa4KzVNLE_4mSQ2J&q=85&s=504cd2c6d728cf06e543c0cbf5c9e4fb" alt="Catalyst Custom Api" width="3552" height="1262" data-path="images/catalyst-custom-api.png" />
    </Frame>

    <Note>
      **Toggle it ON:** By default, this feature is toggled off. Make sure to toggle the Custom API feature **ON** in the Tools menu so your configured APIs are active.
    </Note>

    Click on **Add Custom API** to open the configuration window.
  </Step>

  <Step title="Define the API Name and Trigger Prompt">
    * **Name:** Give your API a recognizable name.
    * **Trigger Prompt:** Describe in human language *when* this API should trigger and *what* it should extract.

    **Example of Trigger Condition:**

    > "Trigger this API after the customer has confirmed their delivery slots."

    **Example of Trigger & Extraction:**

    ```json theme={null}
    Trigger this API after the customer has confirmed their employee ID and extract the employee ID that the customer has mentioned in JSON format:
    {
      "employeeId": "string"
    }
    ```

    <Frame>
      <img src="https://mintcdn.com/superdash/fa4KzVNLE_4mSQ2J/images/catalyst-custom-api-trigger-prompt.png?fit=max&auto=format&n=fa4KzVNLE_4mSQ2J&q=85&s=10670447c1e967263406195e8bddf87a" alt="Catalyst Custom Api Trigger Prompt" width="3506" height="1636" data-path="images/catalyst-custom-api-trigger-prompt.png" />
    </Frame>
  </Step>

  <Step title="Select the Trigger Event">
    Choose exactly when in the call lifecycle this API should execute.

    | Event                 | Description                                                                           | Needs Trigger Prompt?                                  |
    | :-------------------- | :------------------------------------------------------------------------------------ | :----------------------------------------------------- |
    | **Start of the call** | Triggers immediately when the call is received/placed, before the Assistant connects. | No (Prompt is ignored)                                 |
    | **During the call**   | Triggers dynamically based on conversation context.                                   | Yes (Needs trigger condition & extraction if required) |
    | **End of the call**   | Triggers automatically when the call disconnects.                                     | Yes (Extraction instructions only)                     |
    | **Call Status**       | Specific call status triggers.                                                        | No                                                     |

    <Note>
      For more details on Call Status configurations, [click here to read our Call Status Guide](https://docs.google.com/document/d/1nUatfkbc_TgQuXyHl2spl4PJ1nZb_7Z6OLfscgEjnLI/edit?tab=t.0).
    </Note>
  </Step>

  <Step title="Configure Request Details">
    Below the trigger event, configure how the request is made to your server.

    <Frame>
      <img src="https://mintcdn.com/superdash/fa4KzVNLE_4mSQ2J/images/catalyst-custom-api-trigger-event.png?fit=max&auto=format&n=fa4KzVNLE_4mSQ2J&q=85&s=5b2912028fb59fbb578e6e034a762f49" alt="Catalyst Custom Api Trigger Event" width="3562" height="1226" data-path="images/catalyst-custom-api-trigger-event.png" />
    </Frame>

    * **Call Once:** If turned **ON**, the API triggers only one time. If turned **OFF**, it can trigger multiple times whenever the condition is met. *(Note: This toggle only applies to the "During the call" event; all other events inherently only call the API once).*
    * **Method:** Select the HTTP method (**GET**, **POST**, or **PUT**).
    * **URL:** Enter your complete endpoint URL (must include `http://` or `https://`).

    ### Dynamic URLs

    You can make your URL dynamic by wrapping variables in curly braces, such as `https://test.com/test/{ID}/users`. To pass data into this URL, you must add an **Input Param** named `ID`, set its location to **Body**, and turn on **Persist Param** to pull the value from state variables.
  </Step>

  <Step title="Define Audio Responses">
    You can configure static messages that the Assistant will speak to the customer during the API's execution lifecycle.

    <Frame>
      <img src="https://mintcdn.com/superdash/fa4KzVNLE_4mSQ2J/images/catalyst-custom-api-trigger-messages.png?fit=max&auto=format&n=fa4KzVNLE_4mSQ2J&q=85&s=3fdb5053f9b3bbee52493da08dc0e843" alt="Catalyst Custom Api Trigger Messages" width="3562" height="1254" data-path="images/catalyst-custom-api-trigger-messages.png" />
    </Frame>

    * **Back Channel Message:** Played while the API is executing.
      * *Example:* "Please wait while we fetch your details."
    * **Success Response:** Played if the API returns data successfully.
      * *Example:* "We have received your details, can you tell your issue?"
    * **Failure Response:** Played if the API fails or times out.
      * *Example:* "Sorry, we were not able to get the details, is there anything else I could help you with?"
  </Step>

  <Step title="Configure Input Parameters">
    Input parameters define what attributes the Assistant sends to your API. Click **Add Input Param** to configure:

    <Frame>
      <img src="https://mintcdn.com/superdash/fa4KzVNLE_4mSQ2J/images/catalyst-input-params.png?fit=max&auto=format&n=fa4KzVNLE_4mSQ2J&q=85&s=f99ece1e17499f135e1a875cd9bc7c9e" alt="Catalyst Input Params" width="3544" height="1764" data-path="images/catalyst-input-params.png" />
    </Frame>

    | Field              | Description                                                                                                                          |
    | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
    | **Param Name**     | The name of the key (must exactly match the variable in your Trigger Prompt for dynamic extraction).                                 |
    | **Param Type**     | Choose **Static** (a fixed value) or **Dynamic** (extracted from the conversation).                                                  |
    | **Param Value**    | Used only if the type is Static; ignored if Dynamic.                                                                                 |
    | **Param Prefix**   | Optional prefix added before the value.                                                                                              |
    | **Param Location** | Choose where to pass the parameter: **Body**, **Header**, or **Query**.                                                              |
    | **Persist Param**  | If toggled **ON**, the system searches state variables for this Param Name and uses that value (overriding the Type/Value settings). |
  </Step>

  <Step title="Configure Return Parameters">
    Return parameters define what data your API sends back to the Assistant, and how the Assistant should use it. Click **Add Return Param** to configure:

    <Frame>
      <img src="https://mintcdn.com/superdash/fa4KzVNLE_4mSQ2J/images/catalyst-return-params.png?fit=max&auto=format&n=fa4KzVNLE_4mSQ2J&q=85&s=650da1b1aff620fb27c578f705f0daf8" alt="Catalyst Return Params" width="3544" height="1764" data-path="images/catalyst-return-params.png" />
    </Frame>

    | Field             | Description                                                                                                                                         |
    | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Param Name**    | Must match the key returning from your API. Supports nested object paths (e.g., `employee.name` or `user.employee[0].name`).                        |
    | **Persist Param** | If toggled **ON**, the returned field is saved into state variables so the Assistant remembers it for the rest of the conversation.                 |
    | **Use Location**  | Choose **API** or **Prompt**. If **Prompt** is selected, curly brace variables in the prompt (e.g., `{name}`) are replaced with the returned value. |
    | **Return Type**   | Choose **Text** or **Object** (e.g., returning JSON).                                                                                               |
  </Step>

  <Step title="Save Your Configuration">
    Once all parameters and settings are configured, click **Submit** at the bottom right corner of the window.

    <Frame>
      <img src="https://mintcdn.com/superdash/fa4KzVNLE_4mSQ2J/images/catalyst-custom-api-submit.png?fit=max&auto=format&n=fa4KzVNLE_4mSQ2J&q=85&s=bdb8eca853f0dd1c489e9ede654dccbc" alt="Catalyst Custom Api Submit" width="2544" height="674" data-path="images/catalyst-custom-api-submit.png" />
    </Frame>

    Your Custom API is now active! You can repeat this process to add as many Custom APIs as your Assistant needs.
  </Step>
</Steps>