---
title: "Create plugin integration"
method: POST
path: "/plugin-integrations"
tags: ["plugin-integrations"]
---

# Create plugin integration

`POST /plugin-integrations`

Creates a new plugin integration. As part of creation, Productboard sends a
**probe request** (GET) to your configured action URL to verify it is reachable
and intends to receive action notifications. See the `callbacks` section below.

The integration is created in the `enabled` state by default. Set
`fields.integrationStatus` to `disabled` to skip the probe (useful for staged setup).

**`action` is write-only**: the action configuration, including any
`headers.authorization` secret, is never returned in responses.

## Request body

- object
  - `data` object, required
    - `fields` PluginIntegrationCreateFields, required — Domain attributes for creating a plugin integration. Note: `action.headers.authorization` is write-only and never returned in responses.
      - `type` string, required — Type identifier for the integration. Use your reversed domain name as a prefix to ensure global uniqueness (e.g., `com.example.myservice`). Integrations of the same type share the same icon and settings grouping in Productboard.
      - `name` string, required — Human-readable name shown as the column name on the Features board and in Productboard settings.
      - `integrationStatus` 'enabled' | 'disabled' — Controls whether the integration is active: - `enabled` — integration column is visible and the push button is active - `disabled` — integration column is hidden from the Features board
      - `initialState` PluginIntegrationInitialState, required — Configuration of the push button before an entity has been connected to the third-party system.
        - `label` string, required — Label shown on the push button in its initial (unconnected) state.
      - `action` Action, required — Configuration for the action endpoint Productboard calls when a user interacts with a push button (push, unlink, or dismiss).
        - `url` string, uri, required — HTTPS endpoint Productboard calls when a user clicks a push button. Requirements: - Must use `https` - TLS certificate must be valid and signed by a public authority - Must be publicly reachable (no `localhost`, private IPs, or internal addresses)
        - `version` 1, required — Version of the action payload format. Currently only `1` is supported.
        - `headers` ActionHeaders — Custom headers included in every outgoing request from Productboard to your action endpoint — both the creation probe and all action notifications.
          - `authorization` string — Raw value sent in the `Authorization` header of every outgoing request. This field is **write-only** and never returned in API responses. Supports any scheme: - `Basic aGVsbG86d29ybGQ=` - `Bearer <token>` - Any custom single-header auth scheme

## Response `201`

Plugin integration created successfully

- object
  - `data` PluginIntegrationReference, required — Minimal reference to a plugin integration, returned in mutation responses.
    - `id` string, uuid, required — Unique identifier for this plugin integration.
    - `links` PluginIntegrationLinks, required — Links for this plugin integration resource.
      - `self` string, uri, required — URL to retrieve this plugin integration.
      - `connections` string, uri, required — URL to list all connections for this plugin integration.

## Other responses

- `400` — Bad Request - Invalid input format or malformed request
- `401` — Unauthorized - Missing or invalid authentication credentials
- `403` — Forbidden - Insufficient permissions
- `408` — Request Timeout - The server did not receive a complete request within the allowed time
- `422` — Unprocessable Entity - Validation failed (e.g., missing required fields, unknown fields)
- `429` — Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time
- `500` — Internal Server Error - An unexpected error occurred on the server, please retry or contact support

---

[API](https://skmtc.dev/productboard/apis/notes.md) · [All operations](https://skmtc.dev/productboard/apis/notes/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/productboard/notes/revisions/b4004749b60f/schema)