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

Simple Pearl

Use the When to trigger the action field to state the exact moment or condition that fires the API call.

Advanced Pearl

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

1

HTTP Method

Choose GET, POST, PUT, DELETE, or PATCH depending on the API’s requirements.
If your API requires another verb, contact support to request it.

2

URL

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).

3

Headers

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 to automatically inject it into the header at runtime.

4

Body

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.

How to define nested keys

  • 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:

​
customerName
text
​
customerEmail
text
​
street
text
​
city
text
​
productId
text
​
quantity
number

Desired API body:

body.json
{
  "customer": {
    "name": "{{customerName}}",
    "email": "{{customerEmail}}",
    "address": {
      "street": "{{street}}",
      "city": "{{city}}"
    }
  },
  "order": {
    "items": [
      {
        "productId": "{{productId}}",
        "quantity": "{{quantity}}"
      }
    ]
  }
}

Mapping table:

API keyVariable
customer.namecustomerName
customer.emailcustomerEmail
customer.address.streetstreet
customer.address.citycity
order.items[0].productIdproductId
order.items[0].quantityquantity

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

1

1. Create a Credential

Go to Credentials → Add New, choose a Name (a label to help you identify it later), and select OAuth2 as the type.

2

2. Fill Credential Details

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)
3

3. Test Credential

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

1

Assign Test Values

Give sample values to every variable used in the request.

2

Run Test API

Click Test API to send the call.

3

Inspect

  • 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.

Variables

Learn how to create and use variables inside API actions.

Last updated: May 6, 2025