Skip to main content

​
Embedded triggers/actions

This use case is for products with an existing workflow builder or orchestration layer that want Zapier to execute individual action steps via API. This White Label use case differs from the generic Powered by Zapier docs:
  • You do not need to have a public Zapier integration.
  • You can run actions across Zapier’s catalog (you are not limited to actions “owned by” your integration).

​
What you need

  • an access token (server-side)
  • a connection identifier for the user’s connected app account

​
High-level flow

  1. Token exchange: your backend exchanges a partner-signed JWT for an access token.
  2. Check existing connections: list the user’s connections for the app and reuse a valid connection when possible.
  3. Request a connect token (if needed): when you need to connect or reconnect, exchange the access token for a connect token. Include resource set to the Connect UI URL you will open (https://connect.zapier.com/to/{app}), matching Token exchange.
  4. Connect if needed: launch Connect UI with the connect token to create/reconnect a connection and store the resulting connection identifier.
  5. Run the action: create an action run with the access token + connection identifier + action inputs.
  6. Poll for completion: poll run status until complete, then return results to your UI.

​
Build the Action Run payload

Before you can call POST /v2/action-runs/, you need three things: a fresh action id, a valid authentication (connection id), and a complete input object. Use the same White Label access token (Authorization: Bearer …) for listing apps, listing actions, loading inputs/choices, and creating the run.
GET /v2/whitelabel/apps is documented for the MCP White Label use case (AI agent connections & automations). For Action Runs, discover apps with GET /v2/apps (Get Apps [v2]) and your access token, unless API reference explicitly documents otherwise.

​
Discover apps

Use Get Apps [v2] (GET https://api.zapier.com/v2/apps) with: Authorization: Bearer <access_token> Use query, category, ids, limit, and offset as needed. See Retrieving Apps for product patterns (search, categories, pagination). Store the id of the app the user selects. You will use it when listing actions and when opening Connect (https://connect.zapier.com/to/{app} — use the app identifier required by Connection flow / Token exchange for your integration).

​
List actions for the selected app

Call Get Actions (GET https://api.zapier.com/v2/actions) with the same bearer token, passing the selected app (for example app=<app_id>) and any filters your UX needs. Let the user pick an action. Persist the action’s stable key for UX if you want, but POST /v2/action-runs/ must use the ephemeral id returned by Get Actions.
Before every POST /v2/action-runs/, call Get Actions again and use a new id for that run. The id is unique per lookup; the key is stable. This matches the warning in Create and retrieve Action Runs below and keeps runs attributable and debuggable.

​
Build input (dynamic fields)

Action inputs are not arbitrary JSON: they follow Zapier’s field definitions and may require follow-up calls.
  1. Fetch input field definitions using the Partner API pattern described in Fields and Fieldsets (POST to /v2/actions/{action_id}/inputs with the user’s authentication connection id and the inputs collected so far).
  2. For fields with format: SELECT, fetch options from /choices as described in the same guide.
  3. When the user changes a field marked invalidates_input_fields, or when depends_on fields change, refetch /inputs and pass all values collected so far (see the invalidation and dependency examples in Fields and Fieldsets).
  4. Optionally use /outputs from that guide if your UI needs to preview output shape after inputs are set.
When you create the action run, input is the final key/value object keyed by field ids, using the values required by each field type (including choice id values for SELECT fields, per the guide).

​
Resolve authentication (connection id)

The authentication value is the user’s connection identifier for the target app — obtained by listing/reusing connections and/or completing Connect per steps 2–4 on this page and Connection flow / Token exchange.

​
Create the Action Run

Only after you have:
  • a fresh action id from Get Actions,
  • a valid authentication connection id for that app, and
  • a complete input object,
call POST https://api.zapier.com/v2/action-runs/ as documented in Create and retrieve Action Runs below, then poll GET /v2/action-runs/{id}/ until the run completes.

​
Create and retrieve Action Runs

To run an action, make a POST request to the Action Runs endpoint. API reference: /v2/action-runs
Before every POST /v2/action-runs/, call Get Actions again and use a new id for that run. This keeps each run uniquely tracked, debuggable, and attributable.The id is unique per lookup; the key is the action’s stable developer identifier.

​
Create an Action Run (request example)

POST https://api.zapier.com/v2/action-runs/
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "action": "core:89sg4uhs5g85gh53hso59hs399hgs59",
  "authentication": "UHsi8e6K",
  "input": {
    "email": "user@example.com",
    "message": "Hello from White Label!"
  }
}

​
Retrieve an Action Run result (request example)

API reference: /v2/action-runs/ 
GET https://api.zapier.com/v2/action-runs/arun_abc123/
Authorization: Bearer YOUR_ACCESS_TOKEN