Actions API

Actions are TypeScript functions that run on demand and return a result. Unlike syncs, they execute immediately in response to an API call and are designed for write operations or any task that requires a direct response — creating a record, sending a message, fetching computed data, and so on.

All requests must include an Authorization: Bearer <secret-key> header. See Authentication for details.

Trigger action

POST /action/trigger Executes an action function for a specific connection and returns the function’s output. The action function receives the input you provide and executes with the credentials of the specified connection. Execution is synchronous — the request waits until the function completes and returns its result.

Headers

string

required

Bearer <secret-key>

string

required

The ID of the connection the action runs on behalf of.

string

required

The integration ID (unique key) for the connection.

Body

string

required

The name of the action to trigger, as defined in nango.yaml.

any

Input data passed to the action function as nango.input. Can be any JSON-serializable value — object, array, string, or number. The expected shape is defined by your action’s input model in nango.yaml.

Response

The response body is the value returned by the action function’s return statement. The shape is defined by your action’s output model in nango.yaml. If the action returns an object, the response is that object. If it returns void, the response body is empty.

curl -X POST "https://api.nango.dev/action/trigger" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Connection-Id: user-123" \
  -H "Provider-Config-Key: github" \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "github-create-issue",
    "input": {
      "owner": "acme",
      "repo": "backend",
      "title": "Fix login bug",
      "body": "Users cannot log in when 2FA is enabled."
    }
  }'

const issue = await nango.triggerAction<CreateIssueInput, GithubIssue>(
  'github',
  'user-123',
  'github-create-issue',
  {
    owner: 'acme',
    repo: 'backend',
    title: 'Fix login bug',
    body: 'Users cannot log in when 2FA is enabled.'
  }
);

console.log(issue.number); // e.g. 42

Response

{
  "id": 1987654321,
  "number": 42,
  "title": "Fix login bug",
  "state": "open",
  "html_url": "https://github.com/acme/backend/issues/42"
}

Node SDK signature

triggerAction<In = unknown, Out = object>(
  providerConfigKey: string,
  connectionId: string,
  actionName: string,
  input?: In
): Promise<Out>

Trigger action asynchronously

POST /action/trigger with X-Async: true Triggers the action and returns immediately with a job ID, without waiting for the function to complete. Poll the status URL to retrieve the result when it is ready.

Additional header

string

Set to true to trigger the action asynchronously.

Response

string

required

Unique ID for the async action job.

string

required

URL to poll for the result. Make a GET request to this URL with your secret key to retrieve the output when complete.

curl -X POST "https://api.nango.dev/action/trigger" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Connection-Id: user-123" \
  -H "Provider-Config-Key: salesforce" \
  -H "X-Async: true" \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "salesforce-sync-contacts",
    "input": { "accountId": "0015g000003DEXAAA4" }
  }'

// Start async action
const { id, statusUrl } = await nango.triggerActionAsync(
  'salesforce',
  'user-123',
  'salesforce-sync-contacts',
  { accountId: '0015g000003DEXAAA4' }
);

// Poll for result
const result = await nango.getAsyncActionResult({ id });

Response

{
  "id": "action_7f3a9b2c",
  "statusUrl": "/action/action_7f3a9b2c"
}

Node SDK signatures

triggerActionAsync<In = unknown>(
  providerConfigKey: string,
  connectionId: string,
  actionName: string,
  input?: In
): Promise<{ id: string; statusUrl: string }>

getAsyncActionResult<Out = unknown>(
  props: { id?: string; statusUrl?: string }
): Promise<Out>

Error handling

Action errors

When an action function throws an error, the API returns a 400 response with the error message from the function.

{
  "error": {
    "code": "action_script_failure",
    "message": "Failed to create issue: repository not found"
  }
}

Timeout

Actions have a maximum execution time. If the function runs longer than the allowed limit, the request returns a 408 response.

{
  "error": {
    "code": "action_timeout",
    "message": "Action exceeded maximum execution time"
  }
}

Connection not found

If the specified connection does not exist, the API returns 404.

{
  "error": {
    "code": "unknown_connection",
    "message": "Connection not found for connection_id: user-123 and provider_config_key: github"
  }
}

Missing action

If the action name does not match a deployed action for the integration, the API returns 404.

{
  "error": {
    "code": "unknown_action",
    "message": "Action github-create-issue not found"
  }
}

Example: sending a Slack message

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: process.env['NANGO_SECRET_KEY'] });

const result = await nango.triggerAction(
  'slack',
  'user-123',
  'slack-send-message',
  {
    channel: '#engineering',
    text: 'Deployment complete: v1.4.2 is live.'
  }
);

console.log(result.ts); // Slack message timestamp

Example: creating a HubSpot contact

const contact = await nango.triggerAction(
  'hubspot',
  'user-123',
  'hubspot-create-contact',
  {
    email: 'ada@example.com',
    firstname: 'Ada',
    lastname: 'Lovelace',
    company: 'Example Corp'
  }
);

console.log(contact.id); // HubSpot contact ID

Overview

Integrations & Connections

Functions & Proxy

SDKs

Trigger action

Headers

Body

Response

Trigger action asynchronously

Additional header

Response

Error handling

Action errors

Timeout

Connection not found

Missing action

Example: sending a Slack message

Example: creating a HubSpot contact

​Trigger action

​Headers

​Body

​Response

​Trigger action asynchronously

​Additional header

​Response

​Error handling

​Action errors

​Timeout

​Connection not found

​Missing action

​Example: sending a Slack message

​Example: creating a HubSpot contact

Trigger action

Headers

Body

Response

Trigger action asynchronously

Additional header

Response

Error handling

Action errors

Timeout

Connection not found

Missing action

Example: sending a Slack message

Example: creating a HubSpot contact