# API Call

**Application:**\
The API Call is used to retrieve a result from an API and either use it as a variable within a workflow or send the result directly to the customer.

* By clicking on the "API call" component, you will add a white block to your whiteboard
* This block has 2 purple dots. You can connect with any blocks you want. 
* If you need to use them, don't hesitate to contact our team for more detailed guidance.

<figure><img src="/files/LAR5Ocs1EkoOS5oRiZ6p" alt=""><figcaption></figcaption></figure>

<mark style="color:red;">**= Please remember to click the "Save changes" button before leaving.**</mark>

**Explanation of Configurations**

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXd0XvsmKBhdFr9p_-fYQKY1h4O7Rjc348aWE3H9cavaowWK3cKwGaa7ZawZgULtdzM7zLLrnfMmJjiKKrtDyeKdAu2w7kmj82RIaHXXeDAsBNGIJBLk3ixNLMGaQIHb1p9teN5tYd1SY7Wx3a7_gdBOsPU?key=JUAXvKooXgoVpV_DTvFzs_DR" alt=""><figcaption></figcaption></figure>

(1) **Select Method**: You can choose the API call method as either GET or POST. Simply put, GET is used to retrieve data from the API, while POST is used to send data to the API.

(2) **URL**: Enter the URL of the API you wish to call. Example URL: `https://api-staging.cxgenie.ai/api/v1/public-api/example`.

(3) **Header Object**: This section is for configuring the request's header information. You may use it or leave it at the default setting, depending on your usage needs. By default, when creating a block, you’ll see two items:

* **Authorization**: Uses a Bearer token for authentication. Replace "Bearer token" with your actual token.
* **Content-Type**: `application/json`, indicating that the data format being sent is JSON.

(4) **Body**: This section contains the data you want to send with the request. For GET, you usually don’t need a body, but for POST, the body will include the required API data. The default body when creating a block is `{ "key": "string" }`, where "key" should be replaced with the actual value. Example:

```json
{
     "product_id": "PROD002",
   "product_name": "Jeans",
   "quantity": 1,
   "price": 300000
}
```

(5) **Determine Returned Result**:

* **Specified Result**: The API returns a specific result.
* **Random Result**: The result returned will be random.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXewD-weYUO6YuyTDR7LCeanYKvqgvTr1PpDQRg-suCF6Jp-6vkr7Bmun4GVZvKf8KyyIBpLmWPOsbKV47kcC9ucb_yr2C1QwC9pdLrKnvl0weGl3rqzwyCfCDBhjJalPLPImuLpu1qGwUAjD9f8m_ZzIQk?key=JUAXvKooXgoVpV_DTvFzs_DR" alt=""><figcaption></figcaption></figure>

**If you select Specified Result**:

The **"Select the value to retrieve from the API result"** field is where you specify the exact value from the API response you wish to retrieve and use in your workflow.

For instance, if the API returns a JSON object with multiple fields and values, you can input the name of the field (or the path to it) in this field to extract the exact value needed.

Example:

* To have the system return the complete list of `purchase_history`, including all orders and items within each order, input in "Select the value to retrieve from the API result": `data.purchase_history`.
* To get items within the first order in `purchase_history`, input: `data.purchase_history[0].items`. This will return the list of items for the first order (`purchase_history[0]`). Each item will contain details like `product_id`, `product_name`, `quantity`, and `price`.

To get specific values from items, like the `product_name` of the first item in the first order, input: `data.purchase_history[0].items[0].product_name`. Indices \[0], \[1], \[2]... represent the order or product index.

(8) **Select action with the result after calling from API**:

* **Save as variable**: The result from the API is saved as a variable for later use in the workflow. Enter the variable name in the "enter\_variable\_name" field.

**If you select Random Result**:

If you select this option, the system will return a random result from available results:

(6) **Random Target**:

* This field is for selecting the object you want to retrieve a random result from. Choose an object from the list to randomize the result.

(7) **Selected Attribute**:

* This option allows you to select a specific attribute from the chosen object in "Random Target". This is the attribute you wish to retrieve from the API result.

(8) **Select action with the result after calling from API**:

* **Save as variable**: The result from the API will be saved as a variable for later use in the workflow. Enter the variable name in the "enter\_variable\_name" field.

To configure the API to return a random result from this data, you can set it up as follows:

1. **Random Target**:
   * Choose the data object you want to randomize. For example:
     * `purchase_history`: if you want to randomly select a purchase in the history.
     * `preferences`: if you want to randomly select among customer preference attributes.
2. **Selected Attribute**:
   * Select a specific attribute within the object to return. For example:
     * `order_id` if you selected `purchase_history` and only want a random order ID.
     * `product_name` if you selected `items` within `purchase_history` and want a random product name in the order.
   * Leave blank or select the whole object if you wish to return the entire object in `purchase_history` or `items`.
3. **Save as Variable**:
   * Name the variable to store the result. For example:
     * `random_order` to store a random order from `purchase_history`.
     * `random_product` to store a random product from the items list.

Example:

* **Random Target**: `purchase_history`
* **Selected Attribute**: `order_id`
* **Save as Variable**: `random_order`

The returned result will be, for example, `ORD001` if there’s only one transaction. If multiple transactions exist in `purchase_history`, a random `order_id` will be selected.

To return a random product from the purchase history, you might choose:

* **Random Target**: `items` (within `purchase_history`)
* **Selected Attribute**: `product_name`
* **Save as Variable**: `random_product`

This will retrieve a random product name from the customer’s purchase history.


---

# 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://documents.cxgenie.ai/bots/workflow/workflow-components-1/api-call.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.