Skip to main content
The Custom API Request element lets your robot or Avatar communicate with the outside world. Use it to fetch live data from a weather service, submit a form to your CRM, look up inventory, trigger a backend workflow, or exchange data with a Plural Automation frame. Responses are mapped to flow variables using JSONPath expressions, and those variables can be spoken aloud, shown on screen, or used to branch your flow.

​
Add a Custom API Request element

Right-click on an empty area of your canvas and select Custom API request. Click the element once to open the configuration sidebar.

​
Configure the request

​
Request URL

Enter the full HTTPS endpoint URL in the Request URL field. HTTP is not supported — all requests must use a secure HTTPS connection. You can embed flow variables inside the URL using #ATTRI/variableName: 
https://api.example.com/products/#ATTRI/productId

​
Request method

Click the method dropdown to select the HTTP verb:
MethodTypical use
GETRetrieve data without a body
POSTCreate a new resource
PUTReplace an existing resource
PATCHPartially update an existing resource
DELETERemove a resource

​
Request headers

Click Change header to add or modify HTTP headers. Supported header types include:
  • Authorization — authentication credentials (API key, Bearer token).
  • WWW-Authenticate — server-initiated authentication challenges.
  • Accept-Charset — acceptable character sets (e.g., UTF-8).
  • Content-Type — the media type of the request body (e.g., application/json).
  • Cache-Control — caching directives for the request.

​
Request body (POST, PUT, PATCH)

Choose a body type from the dropdown:
Send a JSON object as the body. Enter valid JSON in the editor, using #ATTRI/variableName to inject variable values:
{
  "userId": "#ATTRI/userId",
  "query": "#ATTRI/UserQuery"
}

​
Save response values to variables

After a successful request, map values from the JSON response body to flow variables using JSONPath expressions. In the sidebar, click Add transformation rule and fill in:
​
JSON Path
string
required
A JSONPath expression that points to the value you want to extract. Use $ for the root and .property to navigate object keys.Examples:
  • $.temperature — extracts the temperature field from the root.
  • $.data.user.name — navigates nested objects.
  • $.results[0].title — accesses the first item in an array.
​
Variable name
string
required
The Plural attribute name where the extracted value will be stored. For example: currentTemperature.

​
Use the test button

Click Test request at the bottom of the sidebar to send the request immediately and inspect the raw JSON response. Click on any value in the response to copy its JSONPath automatically.

​
Use saved variables in speech and other elements

Once a response value is stored in a variable, reference it anywhere in your flow with #ATTRI/variableName: 
The current temperature in Berlin is #ATTRI/currentTemperature degrees.
You can also use the variable in subsequent API call URLs, button labels, conditions, and SMS messages.

​
Authentication

Plural supports the following authentication methods:
  • API key — include the key as a custom header (for example, X-API-Key: your_key_here).
  • Bearer token — add an Authorization header with the value Bearer your_token_here.
OAuth and SSL certificate authentication are not supported. If your API requires OAuth, use a middleware proxy that accepts token-based authentication from Plural and handles the OAuth flow on your behalf.

​
CORS workaround

If the API you are calling does not support CORS (cross-origin resource sharing), you will receive a browser-level error when calling it from an Avatar flow. To work around this:
Change the Content-Type header value from application/json to text/plain. Many APIs will still parse the body correctly, and the browser will not enforce CORS preflight for text/plain requests.
This does not apply to robot frames (Pepper, NAO, Temi) where there is no browser-enforced CORS restriction.

​
Requirements profile for API integration

If you are documenting or sharing integration requirements with an API provider, reference these specifications:
  1. Supported methods — POST, PUT, PATCH for write operations; GET for read; DELETE for removal.
  2. Body types — Raw JSON, Raw Text/HTML, Form Data, URL Encoded.
  3. CORS — If CORS is not supported, clients must set Content-Type: text/plain.
  4. Transport security — HTTPS only. HTTP requests are rejected.
  5. Authentication — API key in header or Bearer token. OAuth and SSL certificates are not supported.

​
Connect the outputs

The Custom API Request element has two outputs:
  • Success — the request returned a 2xx HTTP status code.
  • Error — the request failed (network error, 4xx, or 5xx response).
Always connect both outputs so your flow handles API failures gracefully.