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

All RESTful Data Element requests are executed 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

Getting Started

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

Static text that never changes

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

Form Field

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

Secure values stored in the credential center (passwords, API keys, tokens)

  • Example: API keys, authentication tokens
  • Values are encrypted and secure

Server Variable

Values stored 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 they are shared across all RESTful Data Elements in the same form

Environment Variables

Environment variables are special variables that can be replaced anywhere within your request configuration text. Unlike other value sources, environment variables can use any unique string pattern and can be embedded 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 can be used 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

Query Parameters

Add URL parameters that get appended 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
  • Basic: Username/password (from Credentials)
  • Bearer Token: Token-based auth (from Credentials or Server Variable)
  • API Key: Key in header or query parameter (from Credentials)
  • OAuth2: OAuth 2.0 flow (from Credentials)

Body

Configure 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: RESTful Data Element: Server Variables(opens in a new tab)

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


    // Token will automatically be stored in a server variable
    // if the `getToken` had response mapping set to `Server Variable`


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

Server Variables in Detail

Server Variables are perfect for storing data that needs to be reused across multiple API calls:

Authentication Tokens 

// 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 

// 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

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 

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