> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# Create a Slack Connection

`POST https://app.pagerduty.com/integration-slack/workspaces/{slack_team_id}/connections`

Creates a Slack Connection

> ### Important
>
>  Make sure that your PagerDuty account is linked to your Slack workspace and your PagerDuty user is linked to your Slack user. You can do this on the Slack extension page in your PagerDuty account.

> ### Important
>
>  Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary
>  permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the
>  details.

Scoped OAuth requires: `services.read users.read webhook_subscriptions.write priorities.read incidents.read`

## Authorization

- **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`
- **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer <BEARER TOKEN>`

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `slack_team_id` | string | yes | Slack team (workspace) id. |

## Request body (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `slack_connection` | object |  |  |
| `slack_connection.channel_id` | string | yes |  |
| `slack_connection.source_id` | string | yes |  |
| `slack_connection.source_type` | string | yes | Configuration item of the Slack connection that indicates what PagerDuty source would be used for the connection (can be Service or Team). One of: `service_reference`, `team_reference`. |
| `slack_connection.notification_type` | string |  | Configuration item of the Slack connection that indicates how Slack message will be formatted (can be `responder` or `stakeholder`) One of: `responder`, `stakeholder`. Default: `responder`. |
| `slack_connection.config` | object | yes | Item of the Slack connection that contains configuration options (filters). |
| `slack_connection.config.events` | array of string |  | Configuration item of the Slack connection allows you to subscribe to different type of events. |
| `slack_connection.config.urgency` | string \| null |  | Configuration item of the Slack connection allows you to filter events by urgency. One of: `high`, `low`, `null`. |
| `slack_connection.config.priorities` | array \| null |  | Configuration item of the Slack connection that allows you to filter events by priorities. If set to 'null', the connection accepts events of any priority, including those without a specified priority. If set to an empty array, only events without a specific priority are allowed. Otherwise, event filtering adheres to the specific priority codes provided in the array, and the special code 'no_priority' can also be included in the array. |

Example: Request Example

```json
{
  "slack_connection": {
    "source_id": "A1234B5",
    "source_type": "team_reference",
    "channel_id": "A123B456C7D",
    "notification_type": "responder",
    "config": {
      "events": [
        "incident.triggered",
        "incident.acknowledged",
        "incident.escalated",
        "incident.resolved",
        "incident.reassigned",
        "incident.annotated",
        "incident.unacknowledged",
        "incident.delegated",
        "incident.priority_updated",
        "incident.responder.added",
        "incident.responder.replied",
        "incident.status_update_published"
      ],
      "priorities": [
        "ABCDEF1",
        "AB1CDE2"
      ],
      "urgency": null
    }
  }
}
```

## Response 201

Returns created Slack Connection.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `slack_connection` | object | yes |  |
| `slack_connection.id` | string |  |  |
| `slack_connection.source_id` | string |  |  |
| `slack_connection.source_name` | string |  |  |
| `slack_connection.source_type` | string |  | Configuration item of the Slack connection that indicates what PagerDuty source would be used for the connection (can be Service or Team). One of: `service_reference`, `team_reference`. |
| `slack_connection.channel_id` | string |  |  |
| `slack_connection.channel_name` | string |  |  |
| `slack_connection.notification_type` | string |  | Configuration item of the Slack connection that indicates how Slack message will be formatted (can be `responder` or `stakeholder`) One of: `responder`, `stakeholder`. Default: `responder`. |
| `slack_connection.config` | object |  | Item of the Slack connection that contains configuration options (filters). Same fields as `slack_connection.config` above. |

Example: Response Example

```json
{
  "slack_connection": {
    "id": "A12BCDE",
    "source_id": "A1234B5",
    "source_name": "test_team",
    "source_type": "team_reference",
    "channel_id": "A123B456C7D",
    "channel_name": "random",
    "notification_type": "responder",
    "config": {
      "events": [
        "incident.triggered",
        "incident.acknowledged",
        "incident.escalated",
        "incident.resolved",
        "incident.reassigned",
        "incident.annotated",
        "incident.unacknowledged",
        "incident.delegated",
        "incident.priority_updated",
        "incident.responder.added",
        "incident.responder.replied",
        "incident.status_update_published"
      ],
      "priorities": [
        "ABCDEF1",
        "AB1CDE2"
      ],
      "urgency": null
    }
  }
}
```

## Response 400

Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Validation Error

```json
{
  "error": {
    "errors": [
      "Name can't be blank"
    ],
    "message": "Invalid Input Provided"
  }
}
```

Example: Invalid channel_id provided

```json
{
  "error": {
    "message": "Unable to update a Slack Connection: Slack channel name fetch failed"
  }
}
```

Example: Malformed JSON

```json
{
  "error": {
    "message": "Malformed JSON"
  }
}
```

## Response 401

Caller did not supply credentials or did not provide the correct credentials.
If you are using an API key, it may be invalid or your Authorization header may be malformed.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Unauthorized

```json
{
  "error": {
    "message": "Unauthorized"
  }
}
```

## Response 403

Caller is not authorized to view the requested resource.
While your authentication is valid, the authenticated user or token does not have permission to perform this action.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Forbidden

```json
{
  "error": {
    "message": "Forbidden"
  }
}
```

## Response 404

The requested resource was not found.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Not Found

```json
{
  "error": {
    "message": "Not Found"
  }
}
```

Example: Invalid Workspace

```json
{
  "error": {
    "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again."
  }
}
```

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).