---
title: "Run a configured integration"
method: POST
path: "/v1/integrations/execute"
tags: ["Integrations"]
---

# Run a configured integration

`POST /v1/integrations/execute`

## Request

- Base URL: `https://api.workwing.io`
- URL: `https://api.workwing.io/v1/integrations/execute`
- Auth: HTTP bearer

Enqueues the integration and answers 202 with a `queueId`. Add `?wait=true` to hold the connection until the run finishes and receive its result instead: the same fields `GET /v1/integrations/executions/{queueId}` returns, plus `result` with the run's `executionId`, `status`, `output` and `cacheHit`. For an asynchronous integration the wait ends once the request is sent, so read the outcome back by `queueId`.

Under `?wait=true` a run that fails answers 422 with `E_AP_7003 INTEGRATION_ERROR`, carrying the `queueId` and `executionId` in `error.details`; the provider's own error text is recorded server-side and not returned. A run still going after the wait window answers 408 with `E_AP_7002`. Either way, read the run back with `GET /v1/integrations/executions/{queueId}` rather than executing again.

A `jobId` or `customerId` must belong to the key's brand: one in another brand, or one that does not exist, answers 404.

Scope: `execute:integrations`. No `Idempotency-Key` is required on this endpoint.

## Query parameters

- `wait` '0' | '1' | 'true' | 'false'

## Request body

- object
  - `integrationId` string, uuid, required
  - `inputData` object
  - `jobId` string, uuid
  - `customerId` string, uuid

## Response `200`

Default Response

- object
  - `data` object
    - `queueId` string, uuid, required
    - `status` string, required
    - `executionId` string, uuid, nullable, required
    - `executionStatus` string, nullable, required
    - `output` unknown, required
    - `completedAt` string, date-time, nullable, required
    - `result` object, required
      - `executionId` string, uuid, nullable, required
      - `status` string, nullable, required
      - `output` unknown, required
      - `cacheHit` boolean, required
  - `meta` object
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `202`: Queued. Read the outcome back with `GET /v1/integrations/executions/{queueId}`.

---

[API](https://skmtc.dev/workwing/apis/workwing-api.md) · [All operations](https://skmtc.dev/workwing/apis/workwing-api/llms.txt) · [OpenAPI document](https://skmtc.dev/workwing/apis/workwing-api/revisions/54bb14368a35?raw)