> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded triggers/actions

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

# 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](../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.

<Note>
  **`GET /v2/whitelabel/apps`** is documented for the **MCP** White Label use case ([AI agent connections & automations](./ai-agent-connections)). For **Action Runs**, discover apps with **`GET /v2/apps`** ([Get Apps \[v2\]](/powered-by-zapier/api-reference/apps/get-apps-\[v2])) and your access token, unless API reference explicitly documents otherwise.
</Note>

### Discover apps

Use **[Get Apps \[v2\]](/powered-by-zapier/api-reference/apps/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](/powered-by-zapier/zap-creation/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](../connection-flow) / [Token exchange](../token-exchange) for your integration).

### List actions for the selected app

Call **[Get Actions](/powered-by-zapier/api-reference/actions/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.

<Warning>
  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.
</Warning>

### 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](/powered-by-zapier/zap-creation/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](../connection-flow)** / **[Token exchange](../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](/powered-by-zapier/api-reference/actions/create-an-action-run)

<Warning>
  Before **every** `POST /v2/action-runs/`, call **[Get Actions](/powered-by-zapier/api-reference/actions/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.
</Warning>

### Create an Action Run (request example)

```http theme={null}
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/{id}](/powered-by-zapier/api-reference/actions/retrieve-action-run)

```http theme={null}
GET https://api.zapier.com/v2/action-runs/arun_abc123/
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Related guides

* [Token exchange](../token-exchange)
* [Connection flow](../connection-flow)
* [AI agent connections & automations](./ai-agent-connections) — MCP tool-calling for agents
* [Retrieving Apps](/powered-by-zapier/zap-creation/retrieving-apps)
* [Selecting an Action](/powered-by-zapier/zap-creation/selecting-an-action)
* [Fields and Fieldsets](/powered-by-zapier/zap-creation/fields-and-fieldsets)