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.
The ID of the connection the action runs on behalf of.
The integration ID (unique key) for the connection.
Body
The name of the action to trigger, as defined in nango.yaml.
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."
}
}'
{
"id": 1987654321,
"number": 42,
"title": "Fix login bug",
"state": "open",
"html_url": "https://github.com/acme/backend/issues/42"
}
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.
Set to true to trigger the action asynchronously.
Response
Unique ID for the async action job.
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" }
}'
{
"id": "action_7f3a9b2c",
"statusUrl": "/action/action_7f3a9b2c"
}
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
const contact = await nango.triggerAction(
'hubspot',
'user-123',
'hubspot-create-contact',
{
email: '[email protected]',
firstname: 'Ada',
lastname: 'Lovelace',
company: 'Example Corp'
}
);
console.log(contact.id); // HubSpot contact ID
