Integrate with external REST APIs

The RESTful Data Element enables you to:

• Connect to external REST APIs and web services
• Send HTTP requests with data from your form
• Automatically populate form fields with API responses
• Chain multiple API calls together
• Handle authentication and complex request flows

Server-side execution

The server executes all RESTful Data Element requests server-side, which means:

• No CORS Issues — Cross-Origin Resource Sharing (CORS) restrictions don’t apply since requests originate from the server, not the browser
• Enhanced Security — API keys and sensitive data never leave the server environment
• User Access — All authorized users can interact with RESTful form elements regardless of their role — administrator privileges aren’t required

Getting started

This section walks you through adding a RESTful Data Element to your form and configuring its basic settings.

Adding a RESTful Data Element

1. In the form builder, drag the RESTful Data Element from the toolbox onto your form.
2. Give it a meaningful Client ID (e.g. getCustomers, authenticateUser).
3. The element appears as a visual indicator showing the HTTP method and endpoint.
4. Double-click to open the configuration dialog.

Basic configuration

Configure your API request using these main sections:

Request Settings

• HTTP Method — GET, POST, PUT, DELETE, etc.
• URL — Complete endpoint URL (e.g. https://api.example.com/customers)

Value sources

Throughout the configuration, you can use four types of value sources.

Fixed value

This is static text that never changes.

• Example: "application/json" for Content-Type header

Form field

This is a dynamic value from another form field that updates automatically.

• Example: Use a customer ID from a dropdown to fetch customer details
• Test Value — During form design, set a sample value for testing

Credential

The Credential Center stores secure values like passwords, API keys, tokens, and JSON Web Token (JWT) signing credentials.

• Example: API keys, authentication tokens, signed JWT credentials
• The system encrypts and secures these values

Server variable

Store values from previous API calls within the same Workflow form.

• Example: Store an access token from a login API to use in subsequent requests
• Test Value — Set a sample value for testing during form design
• Important — Server variable names must be unique within each form since all RESTful Data Elements in the same form share them

Environment variables

Environment variables are special variables that you can replace anywhere within your request configuration text. Unlike other value sources, environment variables can use any unique string pattern, and you can embed them within larger text strings in:

• URL
• Headers
• Query parameters
• Request body

Environment variable syntax

Environment variables can use any unique string pattern you define:

Bearer __AUTH_TOKEN__
https://{{BASE_URL}}/api/customers
Content-Type: application/json; charset=<ENCODING>
Customer ID: --CUSTOMER_ID--
API Version: VER_2_1

Defining environment variables

In the Variables tab, define variables that you can use throughout your request:

Configuration

• Variable Name — The unique string to be replaced (e.g. __AUTH_TOKEN__, {{BASE_URL}}, <ENCODING>)
• Value Source — Where the replacement value comes from

Configuration tabs

The RESTful Data Element configuration dialog includes several tabs for defining query parameters, headers, request body, response mapping, and events.

Query parameters

Add URL parameters that the system appends to your request URL.

Example:

Name: customerId
Source: Form Field
Field: CustomerDropdown

Results in: https://api.example.com/customers?customerId=12345

Headers

Configure HTTP headers for your request.

Common examples

• Authorization — Bearer {access_token} (from variables mapped from server variable)
• Content-Type — application/json (Fixed Value)
• X-API-Key — {api_key} (from Credential)

Authorization

Configure authentication for your API.

Types available

• None — No authentication
• Signed-in User Token — Token for the signed-in Workflow Automation user
• Basic Authentication — Username/password from Credentials
• Bearer Token — Token-based authentication from Credentials or Server Variable
• OAuth 2.0 — OAuth 2.0 flow from Credentials
• API Key — Key in header or query parameter from Credentials
• Signed JWT (Bearer) — Signed JSON Web Token generated from a Signed JWT credential and sent as a bearer token
• Signed JWT (Basic) — Signed JSON Web Token generated from a Signed JWT credential and sent using HTTP Basic authentication as base64url(subject:token)

For credential-backed authentication types, select the matching credential from Credential Center in the authorization settings. In query parameters, headers, environment variables, and request body mappings, signed JWT credentials expose JWT Token and JWT Basic credential fields. Save the element configuration, and use Test Request to verify the request can be authenticated and accepted by the API.

Body

Configure the request body for POST, PUT, PATCH requests.

Body types

• Raw — JSON, XML, or plain text
• Form URL-Encoded — Traditional form data
• Multipart Form Data — For file uploads

Response mapping

Map API response data to form fields automatically.

Configuration

1. Response Path — JSONata expression pointing to data (e.g. $.customers[*])
2. Map To — Choose Form Field or Server Variable
3. Target — Select the destination field or variable name

Common patterns

• $.data — Extract data object
• $.items[*] — Extract array of items
• $.user.name — Extract nested value
• $.access_token — Extract authentication token

Executing requests

Use JavaScript to execute requests programmatically:

// Get the element by its Client ID.
var getToken = intForm.getElementByClientID('getToken');
var getCustomers = intForm.getElementByClientID('getCustomers');

// Generate a unique run ID.
// The same unique run ID must be passed to all `executeRequest` functions
// in the form.
var runId = intForm.generateUniqueID();

// Execute the request.
await getToken.request.executeRequest(runId);

For more information about runId, see the server variables in detail section below.

Chaining requests

Execute requests in sequence using the onResponse event:

// Execute login first, then get data.
getToken.events.onResponse = async (response) => {
    // Do something with the response if needed.
    console.log('Response from request', response);

    // The system automatically stores the token in a server variable
    // if you set the `getToken` response mapping to `Server Variable`.

    // Execute the next request.
    await getCustomers.request.executeRequest(runId);
}

Server variables in detail

Server variables are perfect for storing data that you need to reuse across multiple API calls.

Authentication tokens

This example logs in, stores the resulting token as a server variable, and reuses it as a bearer token in a later request:

// Login API response mapping:
Response Path: $.access_token
Map To: Server Variable
Variable Name: auth_token
Expiry: Process Completion

// Use in subsequent requests:

// Environment variable.
Variable Name: __ACCESS_TOKEN__
Source: Server Variable
Server Variable: auth_token

// Header param.
Authorization Header: Bearer __ACCESS_TOKEN__
Source: Fixed Value

Shared data

This example stores a customer ID from one response so later requests in the same form can reuse it:

// Store selected customer ID for multiple requests.
Response Path: $.customerId
Map To: Server Variable
Variable Name: current_customer_id

// Use in multiple API calls:
// - Get customer details.
// - Get customer orders.
// - Get customer contacts.

Testing and debugging

You can test your API configuration directly within the form builder and use the browser’s developer console for debugging request and response data.

Test requests

During form design, test your API configuration:

1. Configure your request settings.
2. Set Test Values for Form Fields and Server Variables.
3. Click Test Request.
4. Review response data and verify mappings work correctly.

Error handling

Wrap executeRequest calls in a try/catch block to handle failures gracefully:

try {
    await apiElement.request.executeRequest(runId);
} catch (error) {
    console.error('API request failed:', error);
    // Handle error appropriately.
}