REST API
Overview
The Nected REST API lets you invoke any internal or 3rd party flows over HTTP calls. You can also create a custom integration to any internal or third-party HTTP-based API. Use this integration to configure your API, supporting different types of API authentication, so your team can trigger REST requests in seconds, as part of the rule outcome.
Setting up REST API Connector
Integrating your REST API with Nected allows you to trigger HTTP requests as part of your rule outcomes. This is particularly useful when you want to interact with internal services or third-party APIs to perform operations such as database updates, sending notifications, or invoking business logic.
You can create a connector for both Staging and Production environments. This ensures your API integrations can be tested safely before deploying to production.
Steps to Create a REST API Connector
Follow these steps to configure a REST API connector:
Log in and navigate to Integrations via the left-hand navigation bar.
Under the REST API section, click + Connect to create a new REST API connector.
A configuration form appears. Fill in the required details as described below:
REST API Connector Configuration Fields
Environment Selection
Choose between Staging and Production environments. You must publish the connector in both environments separately. Start with Staging for testing, then repeat the process for Production.
Name
Enter a unique, descriptive name for the connector (e.g., order API).
Base URL
Specify the base URL of your REST API endpoint (e.g., https://api.example.com/v1).
Authentication (optional)
Choose a preconfigured authentication method from the drop-down. If your API requires headers like tokens or Basic Auth, you must define those credentials first on the Credentials page.
Preset Headers (optional)
Define key-value pairs for headers that should be included in every API call. Example: Authorization: Bearer <token>, Content-Type: application/json. You can add multiple headers by clicking + Add Preset Headers.
Preset Query Params (optional)
Add query parameters that should always be included in requests. Example: api_key: 123abc, locale: en_US. Add multiple pairs with + Add Preset Query Params.
Allow-list IP Information
Expand this section to view the Nected IP address (43.205.43.45) which you need to whitelist on your API server or firewall. This is necessary for cloud deployments.
Test Connection
Click Test Connection to verify if Nected can connect to your REST API with the details you’ve provided. Ensure the endpoint is accessible and authentication (if used) is valid.
Publishing the Connector
Once the test is successful, click Publish in Staging to make the connector active in the staging environment.
Important: To use the connector in the Production environment, you must also switch to the Production tab and publish it again after entering the same or updated connection details. Suppose a connector is published only in staging. In that case, it cannot be used in the production environment, and any call to the rule/workflow in the production environment will fail, giving the "connector not published in production" error.
If a connector is not published in either environment, it remains in Draft status and cannot be used in rules. Trying to trigger a rule with an unpublished connector in production will result in the error: "connector not published in production".
Use REST API as Rule Input
You can use data from external REST APIs as dynamic input attributes for your rules. This enables rules to fetch and process real-time data from any HTTP-based service before making decisions or triggering outcomes.
By adding a REST API as an input source, you can automatically populate values based on API responses—without requiring separate data pipeline integrations or manual data handling.
Steps to Add REST API as Input Attribute
Open the Rules page and either create a new rule or edit an existing one.
Navigate to the Input Attributes tab.
Click on the third tab titled Fetch from API (Optional).
Click + Add Input Attribute and define a name for your new input attribute, such as
customerDetailsAPI.From the REST API dropdown:
Select an existing API connector, or
Click + Create REST API to define a new connector. This will redirect you to the Connectors page with the REST API configuration modal pre-opened.
In the modal, configure the REST API connection:
Provide the name, base URL, authentication, preset headers, and query parameters.
Click Test Connection to ensure connectivity.
Click Publish in Staging, then repeat for Production by switching the tab and clicking Publish in Production.
After publishing, return to the Fetch from API tab in the rule editor and click the Refresh ↻ button. Your new connector will appear in the dropdown list.
Configure API for Rule Input
Once an API connector is selected, a configuration modal opens where you must set the specific API behavior for this rule. The following fields are available:
URL Path
Provide the API path relative to the base URL. You can use tokens like {{.customInput.customer_id}} to inject values dynamically from other input attributes.
Method
Choose from supported methods: GET, POST, PUT, PATCH, or DELETE. Depending on the method, additional fields may appear.
Headers
Predefined headers from the connector are automatically applied and cannot be modified here. However, you can add more headers relevant to this specific rule context using key-value pairs.
Query Parameters
As with headers, any preset query parameters from the connector will be auto-filled and immutable. You can add additional dynamic or static query parameters for this request.
Content Type
Appears only if method is POST, PUT, or PATCH. Choose the format of the request payload. Options include: HTML, TEXT, JavaScript, JSON, XML, FORM, FORM URL Encoded.
Request Body Editor
Appears with POST, PUT, PATCH methods. Write the request body in the format specified above. Use tokens to dynamically inject values from custom inputs (e.g., {{.customInput.customer_email}}). The content will be sent to the API in its native type, but returned output will be shown in JSON format in the UI for easy inspection.
Tip: You can use tokens inside the URL path along with the value fields of both Headers and Query Parameters to make your HTTP requests dynamic. Just start typing with {} and a list of available tokens will appear—these can include workflow inputs, outputs from previous nodes, or other dynamic values. This allows your API calls to adapt at runtime based on real-time data.
Content Types and Request Body Configuration
The Content Type determines how your request body data is formatted and interpreted by the receiving API. Choose the content type that matches what your target API expects.
JSON (application/json)
Most modern REST APIs expect JSON format. This is the most common choice for structured data.
Request Body Example:
{
"customer_id": "{{.customInput.customer_id}}",
"email": "{{.customInput.customer_email}}",
"order_details": {
"product_id": "{{.customInput.product_id}}",
"quantity": {{.customInput.quantity}},
"total_amount": {{.customInput.total_amount}},
"currency": "USD"
},
"metadata": {
"source": "nected_rule",
"timestamp": "{{.customInput.current_timestamp}}"
}
}XML (application/xml)
Legacy systems or SOAP-based APIs often require XML format.
Request Body Example:
<?xml version="1.0" encoding="UTF-8"?>
<customer>
<id>{{.customInput.customer_id}}</id>
<email>{{.customInput.customer_email}}</email>
<order>
<product_id>{{.customInput.product_id}}</product_id>
<quantity>{{.customInput.quantity}}</quantity>
<total_amount>{{.customInput.total_amount}}</total_amount>
</order>
<metadata>
<source>nected_rule</source>
<timestamp>{{.customInput.current_timestamp}}</timestamp>
</metadata>
</customer>
FORM (application/x-www-form-urlencoded)
Traditional web forms or APIs that expect form-encoded data.
Request Body Example:
customer_id={{.customInput.customer_id}}&email={{.customInput.customer_email}}&product_id={{.customInput.product_id}}&quantity={{.customInput.quantity}}&total_amount={{.customInput.total_amount}}&source=nected_rule
Token Usage Tips:
Values are automatically URL-encoded
Use
&to separate key-value pairsNo quotes needed around token values
FORM URL Encoded (multipart/form-data)
File uploads or complex form submissions with multiple data types.
Request Body Example:
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="customer_id"
{{.customInput.customer_id}}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="email"
{{.customInput.customer_email}}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="order_data"
{"product_id": "{{.customInput.product_id}}", "quantity": {{.customInput.quantity}}}
------WebKitFormBoundary7MA4YWxkTrZu0gW--
TEXT (text/plain)
Simple text data or custom formats that don't fit other categories.
Request Body Example:
Customer ID: {{.customInput.customer_id}}
Email: {{.customInput.customer_email}}
Product: {{.customInput.product_name}}
Quantity: {{.customInput.quantity}}
Order Total: ${{.customInput.total_amount}}
Processing Date: {{.customInput.current_date}}
HTML (text/html)
When sending HTML content, such as email templates or web content.
Request Body Example:
<!DOCTYPE html>
<html>
<head>
<title>Order Confirmation</title>
</head>
<body>
<h1>Hello {{.customInput.customer_name}}!</h1>
<p>Your order #{{.customInput.order_id}} has been confirmed.</p>
<div>
<strong>Product:</strong> {{.customInput.product_name}}<br>
<strong>Quantity:</strong> {{.customInput.quantity}}<br>
<strong>Total:</strong> ${{.customInput.total_amount}}
</div>
<p>Thank you for your purchase!</p>
</body>
</html>
JavaScript (application/javascript)
Rarely used, mainly for APIs that execute JavaScript code or JSONP callbacks.
Request Body Example:
function processOrder() {
var customerId = "{{.customInput.customer_id}}";
var email = "{{.customInput.customer_email}}";
var orderData = {
productId: "{{.customInput.product_id}}",
quantity: {{.customInput.quantity}},
total: {{.customInput.total_amount}}
};
return orderData;
}
processOrder();
After configuring the API, click the Fetch Input Attribute via API button to retrieve and test the data. You’ll see the fetched response displayed in JSON format on the Input Attribute tab.
If the response looks correct, click Save & Close to store the API input configuration. Then click Save and Close on the input attribute panel to finalize.
Response Caching (Optional)
To optimize performance and reduce unnecessary API calls, you can enable Response Caching:
In the Fetch from API tab, select an API or click Edit on an existing one.
Navigate to the Settings tab within the configuration modal.
Toggle the Response Caching option to ON.
Configure caching behavior using the following options:
Key Parameters
Specify the input fields whose values will be used to determine the uniqueness of cached responses. Example: customer_id, country.
Cache Expiry Time
Define how long cached responses should remain valid. You can set this in Days, Hours, or Minutes.
Clear Cache
Manually clear the cache for either Staging or Production if data has changed or you want to force fresh fetches.
This caching mechanism ensures efficient performance in production environments and avoids repeated calls to slow or rate-limited APIs.
Once configured and saved, the fetched data from the REST API is now available as an input attribute for your rule logic, ready to be used in both conditions and results.
Trigger REST API as Rule Actions
You can also define REST API calls as Actions within a rule. This enables your rule to trigger an HTTP request when a condition is met—such as updating a record, notifying another service, or logging activity externally.
You can use REST API connectors already configured in your environment or create a new one while setting up the rule action. These actions are executed at runtime and can be used in both Staging and Production environments.
Steps to Add a REST API as an Action in a Rule
Open Nected and go to the Rules page.
Click + Create Rule to start a new rule or open an existing one. Select either SimpleRule or DecisionTable.
Define your rule’s condition(s).
Click Add Action, then select a configured REST API connector from the dropdown.
The REST API Action configuration modal opens. Fill in the required fields as described below.
REST API Action Configuration Options
URL Path
Define the specific endpoint path relative to the base URL. You can use dynamic tokens such as {{.customInput.user_id}} to construct URLs based on runtime data.
Method
Choose from standard REST methods: GET, POST, PUT, PATCH, DELETE. Method selection determines whether a body and content type are needed.
Headers
Headers configured at the connector level are automatically included and cannot be modified here. You can add more headers using key-value pairs to support additional custom needs such as x-api-version or Correlation-Id.
Query Parameters
Predefined query params from the connector are automatically included. Additional query parameters specific to this rule action can be added dynamically. Tokens can be used for dynamic values.
Content Type
Only appears for POST, PUT, and PATCH methods. Select the format of the request body: HTML, TEXT, JavaScript, JSON, XML, FORM, or FORM URL Encoded.
Request Body
Appears when a method requiring a payload is selected. This is where you define the data to send in the request. The format must match the selected content type. Dynamic tokens are supported. Although the API can handle multiple formats, the UI always renders the response in JSON for readability.
After configuring the action, save the configuration for the REST API action.
Then, to check if it is working or not, click Test in Staging.
Provide the required test inputs.
If the rule condition is satisfied, the configured action (i.e., the REST API call) will be triggered.
On success, a Success status message appears in the Action tab.
Expand the dropdown in the Action tab to inspect the API response. The response is displayed in JSON format and can be used for debugging or validating the rule's behavior.
Once the rule is saved, the REST API action will be executed automatically whenever the rule conditions are met during real-time evaluations.
Troubleshooting
When working with API calls in your rule actions, it's important to be aware of potential errors that may arise during the process. While API calls are primarily HTTP-based, the main categories of errors you might encounter are HTTP status codes, particularly those in the 500 series. However, it's essential to note that Nected does not display the 404 error ("{"error":"Endpoint not found"}") even during API integration.
Here are some common errors you may face and how to address them:
HTTP 500 Series Errors:
What to Expect: These errors indicate that the server has encountered an issue while processing the API request. They can be caused by various factors, such as server misconfigurations or issues on the API provider's end.
How to Resolve:
Check API Endpoint: Ensure that the API endpoint you are calling is correct and accessible.
Verify Request Data: Double-check the data you are sending in your API request. Ensure it adheres to the API provider's requirements.
Contact API Provider: If the issue persists, reach out to the API provider's support for assistance or information on the specific error.
HTTP 404 Error:
Important Note: Nected does not display this error in the API integration stage, but it is essential to be aware of it.
What to Expect: The 404 error typically indicates that the API endpoint could not be found. If you encounter this error, it's likely a result of an issue on your end.
How to Resolve:
Check API Endpoint: Verify that the API endpoint is accurate and exists.
Review Configuration: Review your rule action's configuration to ensure you are calling the correct endpoint and passing the necessary data.
Monitor Output: After including the API as a rule action, make it a habit to monitor the JSON output in the action tab. This will help you identify any 404 errors.
HTTP 403 Error:
What to Expect: An HTTP 403 error signifies that your request has been denied access. This can occur due to various reasons, such as inadequate permissions or IP blocking.
How to Resolve:
Whitelist Nected's IP: If you receive a 403 error, it may be necessary to whitelist Nected's IP address, which is "43.205.43.45". This ensures that Nected can access and interact with the API without any access restrictions.
It's essential to understand that while Nected provides tools for integrating APIs and configuring rule actions, certain errors may be outside of Nected's control, particularly those related to the API provider's infrastructure or your rule action's setup. Regularly monitoring the JSON output and staying vigilant about your API calls will help you quickly identify and address any potential issues. If problems persist, don't hesitate to reach out to the API provider's support for assistance and guidance.
Last updated