> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nlpearl.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Action
> Configure the “API” action in SimplePearl and AdvancedPearl to fetch or update data during a live conversation.
Connecting your Pearl to external systems with **API calls** lets it pull or push data in real time while talking to a customer.
This guide covers :
1. How API Actions differ in **Simple Pearl** vs **Advanced Pearl**
2. Every field you can configure (method, URL, headers, body, credentials)
3. Output‑schema filtering & variable assignment
4. How to test your configuration before going live
***
## API Action Modes
Use the **When to trigger the action** field to state the exact moment or condition that fires the API call.
Add an **API node** inside the conversation tree. As soon as the flow reaches that node, the request runs automatically—no trigger field needed.
**Pre‑Call API (AdvancedPearl only)**\
You may run a request *before* the call starts—perfect for:
* **Inbound**: look up the caller by phone number (auto‑captured variable)
* **Outbound**: preload variables already stored on the lead\
For details see the Outbound Lead Creation page.
***
## Configuring an API Action
Choose **GET**, **POST**, **PUT**, **DELETE**, or **PATCH** depending on the API’s requirements.\
If your API requires another verb, [contact support](mailto:support@nlpearl.ai) to request it.
Type the API endpoint URL.\
Click **+** to insert a variable into the URL — you can use both **Pre-Call variables** (collected before the call starts) and **In-Call variables** (collected during the conversation).
Add any header required by the API, such as `Content-Type`, `Authorization`, etc.
Header values are static. If you need a **dynamic authorization token**, configure an [OAuth2 Credential](/pages/api_action#oauth2-credentials) to automatically inject it into the header at runtime.
Supply Key / Value pairs as required by the API.
Each **Value** field can be:
* A variable
* A Text (string literal)
* A Whole Number (integer)
* A Decimal Number (float or double)
* A Boolean (true/false)
* A Date & Time
* A **Custom Template** (a mix of static text and variables)
For each variable, you can toggle a **"Required" checkbox**:
* If checked, Pearl will automatically prompt the customer to provide the variable’s value before sending the API request, if it hasn’t been collected yet.
* If unchecked, the API request will still be sent even if the variable is missing. In that case, the variable will simply be omitted from the request body.
When using a variable in the body, be aware that:
* The platform will **cast the variable to the corresponding data type** when sending the request.
* For example, a variable of type **Whole Number** will be sent as an integer, while a **Text** variable will be quoted as a string.
* If the variable type doesn’t match what the API expects, the API might reject the request or throw an error.
You can mix static values and variables in the same request body to create dynamic payloads.
If the API expects a nested JSON object, you can use **dot notation** in the Key to define nested paths (e.g., `customer.address.street`).
Arrays can be represented using square brackets with an index (e.g., `order.items[0].productId`). see bellow Nested objects.
***
Additional notes
* You can configure different API Actions inside the same Pearl if your flow needs multiple calls.
* Every API Action can use a different set of variables, headers, and credentials.
* You can use variables in **URL**, and **Body** to pass dynamic data collected during the call.
***
### Using Nested Objects in API Actions
Many APIs expect a **nested JSON structure** in their request body.\
You can map variables to **nested keys** so your payload remains well organised and readable.
* Use **dot notation** for properties (`customer.address.street`)
* Use **square brackets** for array indices (`order.items[0].productId`)
You can pair nested paths with any variable type—Text, Number, Boolean, etc.
### Example
Variables collected:
Desired API body:
```json body.json theme={null}
{
"customer": {
"name": "{{customerName}}",
"email": "{{customerEmail}}",
"address": {
"street": "{{street}}",
"city": "{{city}}"
}
},
"order": {
"items": [
{
"productId": "{{productId}}",
"quantity": "{{quantity}}"
}
]
}
}
```
***
Mapping table:
| API key | Variable |
| -------------------------- | --------------- |
| `customer.name` | `customerName` |
| `customer.email` | `customerEmail` |
| `customer.address.street` | `street` |
| `customer.address.city` | `city` |
| `order.items[0].productId` | `productId` |
| `order.items[0].quantity` | `quantity` |
If the body contains deeper nesting or arrays, this mapping guarantees every variable lands at the correct path.
***
## OAuth2 Credentials
If your API requires OAuth2 authentication, you’ll need to create a **Credential** on the platform to automatically manage token retrieval and injection.
This allows the platform to securely fetch an access token and automatically insert it into your API request headers.
Why use a Credential?
* Avoid hardcoding tokens manually in every API action
* Automatically refresh tokens based on TTL (time‑to‑live)
* Centralized management if multiple API actions reuse the same token
* No need to manually parse token responses — the platform extracts it for you
***
### How to configure a Credential
Go to **Credentials → Add New**, choose a **Name** (a label to help you identify it later), and select **OAuth2** as the type.
You’ll be asked to provide:
* **Access Token URL**: the API endpoint to request the token
* Optional **headers** (e.g. `Content-Type: application/json`) for the token request
* Optional **body** parameters (e.g. `grant_type`, `client_id`, `client_secret`)
* **Token Config**:
* `token path`: JSONPath to locate the token in the API response (e.g. "response.access\_token")
* `ttl`: time‑to‑live for the token (default **300 seconds**; adjust if needed)
* `header key`: name of the header where the token will be injected (e.g. `Authorization`)
* `header prefix`: optional prefix for the token (e.g. `Bearer` or `Basic`)
Use the **Test Credential** button to send a request to the token endpoint and preview the JSON response.
This test confirms that your configuration retrieves the token successfully.
### How the Credential is used in API actions
Once saved, you can select this Credential from the **Credential** dropdown in any API Action.
When selected:
* The platform automatically adds the token to the API request header, using the configured `header key` and optional `header prefix`.
* The token is refreshed automatically when expired, based on the configured `ttl`.
If you don’t need authentication, simply leave the Credential toggle off.
Make sure the `token path` you enter corresponds to the exact location of the token in the JSON response.\
If the platform can’t find the token at this path, the Credential will fail.
***
## Output Schema & Variable Assignment
API responses are capped at **10 000 characters**. Anything longer is automatically truncated.
When using API actions, it’s crucial to control what part of the response is passed back into the conversation. That’s where the **Output Schema** comes in: it lets you filter the API response so only specific data is kept.
Without filtering, the entire JSON is returned — including irrelevant or unnecessary data. This can reduce the precision of the conversation, because the AI receives too much unrelated information.
Even if your API response is well under **10 000 characters**, we strongly recommend setting an Output Schema to focus the conversation on relevant data.
***
### How it works
* Provide a list of **JSONPath strings**.
* The system extracts only those paths from the API response.
* Everything else is discarded.
Benefits:
* Keeps the response size small
* Improves the quality and relevance of AI outputs
* Prevents hitting the 10 000-character truncation limit
* Ensures that only the necessary fields are carried into the next steps of the conversation
### Assigning to a variable (optional)
You can assign the value from a JSONPath directly to a variable.
Key things to know:
* **The variable’s type must match the data type returned by the API at that path.**
* If the value returned is a list, make sure the variable is configured to **allow multiple values.**
* A variable can store up to **600 characters.** Any data beyond this limit will be **truncated.**
Assigning a variable is optional.\
If you don’t assign a variable, the filtered JSON is still available for the conversation’s internal logic but may not be stored under a variable it should be if it is not obvious.
In many cases, assigning variables helps later actions reuse that data (e.g. using a customer’s name in a message, or passing an ID into another API call).
***
### Why Output Schema is critical
Without an Output Schema:
* The conversation may receive **unnecessary data**, lowering the accuracy of Pearl.
* You risk hitting the **10 000-character response cap** and losing critical data.
* This is the best way to map data directly to variables.
By setting an Output Schema:
* You control what gets passed into the conversation logic
* You improve Pearl decision‑making by focusing on relevant fields
* You unlock the ability to assign variables with safe and predictable data
Remember: if you assign to a variable, and the returned data exceeds **600 characters**, the variable’s value will be **cut off**.
***
## Testing Your API Action
Give sample values to every variable used in the request.
Click **Test API** to send the call.
* Raw response
* Filtered response (if you set an Output Schema)
* Any variables populated from the response
Use this tool to debug and perfect your setup before you put the Pearl in production.
***
Learn how to create and use variables inside API actions.
***
*Last updated: May 6, 2025*
