# REST API

This page explains how to establish REST API integration between Customer v2 and an external service. The API's can be used in multiple flows and can be configured with variable placeholders to allow reuse in multiple scenarios. 

Follow a step-by-step tutorial to [Configure an Open Meteo REST API ](https://docs.ixhello.com/ixhc2/general/tutorials/configure-open-meteo-rest-api)connection.

## Before You Begin <a href="#before-you-begin" id="before-you-begin"></a>

* Confirm you know the **API** you want to connect to and the **authorization requirements** needed perform API calls.&#x20;
* Think about what information returned from the API call is relevant to complete the flow and how to parse it for the user.&#x20;

## Accessing the REST API Configuration <a href="#accessing-the-chat-widget-configuration" id="accessing-the-chat-widget-configuration"></a>

1. Sign in to **ixHello Customer v2**.
2. In the left navigation menu, go to **Integrations → REST API**.
3. Settings

<table><thead><tr><th width="220">Setting</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>This column lists the <strong>name of each REST API configuration</strong> created in the system.</td></tr><tr><td>Description</td><td>This column provides a <strong>brief explanation or label</strong> for what the API is used for. </td></tr><tr><td>Last Updated</td><td><p>Shows the <strong>most recent date and time</strong> when each REST API configuration was modified.</p><p>Example formats: <em>02/03/2026, 09:26:15</em>.</p></td></tr><tr><td>Base URL</td><td>The base URL is the common starting point for all API requests. It typically includes the protocol and domain name. <code>https://api.example.com</code></td></tr><tr><td>Action Column</td><td><p>On the far right, although not labeled as a header, each row has an <strong>"Edit"</strong> option.</p><p>This lets users open the selected API configuration and update details such as:</p><ul><li>Base URL</li><li>Headers</li><li>Authentication</li><li>Request/response mapping</li></ul></td></tr></tbody></table>

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FP4UTyqYo56pECRuQHWiM%2Fimage.png?alt=media&#x26;token=4abbdcfb-dbeb-44d5-a17c-ee049c5ddf60" alt=""><figcaption></figcaption></figure>

3. Select **Create connection** or open an existing REST API to edit. The detail page includes:&#x20;
   1. A **header** displaying the Name and the description. Click **edit** to update the base URL and authorization values.&#x20;
   2. A **list view** of configured methods for this API.&#x20;

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FfAntmvRplb3vtaLFQ3ic%2Fimage.png?alt=media&#x26;token=ceed2e03-9daf-4a40-a6e4-e3e98da20576" alt=""><figcaption></figcaption></figure>

## Configuring the REST API <a href="#step-1-define-widget-details" id="step-1-define-widget-details"></a>

### Step 1: REST API settings&#x20;

Setup of the overarching settings that will be used by all methods

<table><thead><tr><th width="220">Setting</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>The meaningful name for the REST API.</td></tr><tr><td>Description</td><td>A description to provide further information. </td></tr><tr><td>Base URL</td><td>The base URL is the common starting point for all API requests. It typically includes the protocol and domain name. <code>https://api.example.com</code></td></tr><tr><td>Authorization type</td><td><p>The authentication method used for requests to this API.</p><p>Authorization type specific input fields become available after selection.</p><p>Either <code>No authorization</code>, <code>Basic Auth</code>, <code>Bearer Token</code> or <code>OAuth 2.0</code>.</p></td></tr></tbody></table>

### Step 2: Method request

Setup of the specific method for this API.&#x20;

<table><thead><tr><th width="220">Setting</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>The meaningful name for the REST API.</td></tr><tr><td>Description</td><td>A description to provide further information. </td></tr><tr><td>Request type</td><td><p>The request type defines how the method is allowed to act with the endpoint.</p><ul><li><code>GET</code> retrieves information or data from a specified resource</li><li><code>POST</code> submits data to be processed to a specified resource</li><li><code>PUT</code> updates a specified resource with new data</li><li><code>PATCH</code> partially updates a specified resource</li><li><code>DELETE</code> deletes a specified resource</li></ul></td></tr><tr><td>Method path *</td><td>The relative path of the specific API endpoint. It is added to the <code>base URL</code> to form a complete request address. A method path of <code>/flows</code> results in a complete request address of <code>https://api.example.com/flows</code></td></tr><tr><td>Query String *</td><td><p>The query string can include one or more parameters. Each parameter is represented by a unique key-value pair or a set of two linked data items. An equal's sign <code>=</code> separates each key and value. The query string is prefixed with a question mark <code>?</code> and added to the end of the complete request address. A query string of <code>api_key=1234567&#x26;user_id=456</code> results in</p><p><code>https://api.example.com/flows?api_key=1234567&#x26;user_id=456</code></p></td></tr><tr><td>Request Headers *</td><td>Request headers are key-value pairs used to transfer metadata about the request.</td></tr><tr><td>Request Body *</td><td><p>The request body contains the actual data being transferred between the client and the server, in JSON format.</p><p><code>{ "data": { "user": { "name": "John", "age":30 } } }</code></p></td></tr></tbody></table>

{% hint style="warning" %}
In release 1.3 The Request Body field is located below the response configuration fields.&#x20;
{% endhint %}

{% hint style="info" %}
Setting with an \* allow for variable substitution by placing a variable name between double curly brackets `{{userName}}`. It becomes a request variable that needs to be populated when configuring an API call node in the Flow editor.
{% endhint %}

#### Variable substitution throughout iX Hello Customer v2

| **API Method**                                                                                                            | **API Call node**                                                                                                                                                                                       | **Runtime**                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Instead of setting a hardcoded customer ID value a variable is defined called `{{customerID}}` to allow reuse of the API. | <p><code>{{customerID}}</code> request variable needs to be populated to successfully call the API.</p><p>An agent node in the flow is configured to gather the end user’s <code>customerID</code>.</p> | <p>The flow asks the end user their <code>customerID</code>, to populate the request variable e.g. <code>1234</code>.</p><p><code>{{customerID}}</code> = <code>customerID</code> = <code>1234</code></p><p><code>1234</code> is sent in the API request.</p> |

* `https://api.example.com/flows/{{customerID}}`
* `https://api.example.com/flows/1234`

### Step 3: Method result \[Beta] <a href="#method-result-beta" id="method-result-beta"></a>

<table><thead><tr><th width="220">Setting</th><th>Description</th></tr></thead><tbody><tr><td>Result type</td><td>Define if the result type is a single <code>entry</code> or a <code>list</code> of entries</td></tr><tr><td>Result path</td><td><em>Optional</em></td></tr><tr><td>Record path</td><td><p><em>Optional</em></p><hr><p>JSON path expression to target an object in API response. <code>$.[*]</code></p></td></tr><tr><td>Record template</td><td><p><em>Optional</em></p><hr><p>Define a template for presenting the result. Refer to fields that are available in the object that is defined in the record path. e.g. <code>Transaction ID: {{transactionId}}, Name: {{user.name}</code></p><p>The result, or list of results is stored in the hardcoded variable <code>{{Records}}</code></p></td></tr><tr><td>Record limit</td><td><p><em>Optional</em></p><hr><p>Set a numeric limit on the number of results that is returned. Only affects result type <code>List</code>.</p></td></tr><tr><td>Valid result template</td><td><p><em>Optional</em></p><hr><p>Define the template in case of a successful API call. e.g.</p><p><code>Found: {{Records}}</code></p></td></tr><tr><td>Empty result template</td><td><p><em>Optional</em></p><hr><p>Define the template in case of a failed API call e.g. <code>No results</code></p></td></tr></tbody></table>

## Next Steps <a href="#next-steps" id="next-steps"></a>

Once you’ve configured and saved your REST API configuration, they can be selected and configured in an [API call node](https://docs.ixhello.com/ixhc2/flows/flow-editor/api-call).&#x20;

Follow the [Open Meteo](https://docs.ixhello.com/ixhc2/general/tutorials/configure-open-meteo-rest-api) tutorial to setup a REST API configuration in preparation for a Weather Flow.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ixhello.com/ixhc2/integrations/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.