Actions within Nango are designed to facilitate performing specific tasks synchronously with external APIs, such as creating a contact in Hubspot or sending a message via Slack. Unlike syncs, actions require manual triggering and can provide immediate responses, making them ideally suited for dynamic, real-time interactions.

​

Use cases for Actions

Actions shine in scenarios requiring two-way syncing or direct data manipulation. For instance, while syncs could be used to regularly import the latest contacts from Hubspot, actions enable the creation or modification of those contacts directly from your application. This capability ensures a seamless flow of information both to and from external services.

​

Main characteristics

​

Code-based workflow

Actions differ significantly from proxies by executing integration scripts rather than mere individual requests. This allows for complex workflows, involving intricate request orchestration and data transformations, to be executed seamlessly.

​

Transient execution

Action executions are transient, with no data persistence on Nango’s part. This ensures that each action is performed in real-time, with the latest data and without reliance on cached information.

​

Defined inputs and outputs

Actions are defined with explicit input parameters and output responses. These schemas are meticulously outlined as models within the integration configuration, ensuring clarity and consistency in data handling.

​

Endpoint access

Once enabled, actions are accessible through specific endpoints, each with an automatically generated API reference available in the Nango UI. This setup facilitates easy integration and execution of actions within your application.

​

Immediate feedback

The outcomes of action executions, whether errors or successes, are directly relayed in the response to your trigger request. This immediate feedback loop empowers you to handle retries or further processing as needed.

​

Unified modeling

Actions support inputs and outputs that adhere to unified models, streamlining the integration process across different external APIs.

Action vs. the proxy

Actions handle more complex scenarios that require multiple requests or data transformations, while the Proxy works for individual API requests.

​

Action scripts

Action executions are powered by integration scripts that encapsulate the logic for interfacing with external APIs. While Nango provides script templates for common use cases, there’s also support for custom scripting to meet specific integration needs.

Action scripts have the following structure:

import type { NangoAction, ResponseModel, ParameterModel } from '../../models';

export default async function runAction(
    nango: NangoAction, 
    input: ParameterModel): Promise<ResponseModel> {
    // Your integration code goes here.
}

The runAction function kicks off when an action is triggered. It takes inputs from the trigger API/SDK request and returns outputs in the response. The ParameterModel and ResponseModel are configurable via the integration configuration and are auto-imported into your integration script.

Actions focus solely on immediate tasks without persisting data to Nango’s cache, thus calls to nango.batchSave(), nango.batchUpdate(), and nango.batchDelete() are not applicable. However, actions can call other actions, enabling complex workflows through the composition of multiple actions.

​

Getting started with actions

Check out the actions step-by-step guide or refer to the reference (API / SDK).