Embedded actions

Use White Label to run actions from your product via Zapier APIs (Action Runs).

Embedded 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)
• an authentication ID 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, then resolve the authentication ID for that app.
5. Run the action: create an action run with the access token + authentication ID + action inputs.
6. Get results: either
   • Poll for completion: poll run status until complete, then return results to your UI, or
   • Use callbacks: optionally set up a callback URL to receive run results

Build the Action Run payload

Before you can call POST /v2/action-runs, you need three things: a fresh action id, a valid authentication (authentication ID), and a complete inputs 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 inputs (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 Workflow 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 (check the invalidation and dependency examples in Fields and Fieldsets).
4. When any field listed in a SELECT field’s choice_depends_on changes, refetch /choices for that field and pass all values collected so far in inputs. choice_depends_on can include optional fields and the field itself: to drill into a nested dropdown (for example, folders), request /choices again with the chosen value as that field’s own value.
5. Optionally use /outputs from that guide if your UI needs to preview output shape after inputs are set.

When you create the action run, inputs 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 (authentication ID)

The authentication value is the user’s authentication ID for the target app. If the user already has a connected app account, use Get Authentications (GET /v2/authentications?app=<app_id>) to list the authentication IDs available for that app.

If the user just completed Connect, do not assume every identifier returned by the browser flow can be passed directly to Action Runs. After Connect completes, call GET /v2/authentications?app=<app_id> with the same access token and use the returned authentication id for the authentication field.

Create the Action Run

Only after you have:

• a fresh action id from Get Actions,
• a valid authentication ID for that app, and
• a complete inputs 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

{
  "data": {
    "action": "core:89sg4uhs5g85gh53hso59hs399hgs59",
    "authentication": "UHsi8e6K",
    "inputs": {
      "email": "[e-mail]",
      "message": "Hello from White Label!"
    },
    "callback_url": "https://example.com/post_callback"
  }
}

Retrieve an Action Run result (request example)

If a callback_url is passed, you will receive the run result via webhook when it completes.

Otherwise, poll for the run status and result using the run ID returned in the create response: /v2/action-runs/

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

Related guides

• Token exchange
• Connection flow
• AI agent connections & automations — MCP tool-calling for agents
• Embedded triggers — subscribe to real-time events via the Trigger Inbox API
• Retrieving Apps
• Selecting an Action
• Fields and Fieldsets