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

# Integrations API: Connect and Manage Third-Party Services

> Use the Integrations API to list, connect, configure, and disconnect third-party services in your Google workspace via a REST interface.

The Integrations API lets you extend Google by connecting it to the tools your team already relies on. Whether you are programmatically setting up Slack notifications as part of a workspace provisioning script, querying the status of an existing GitHub sync, or building an admin dashboard that surfaces all active connections at a glance, every integration lifecycle operation is available through this API. All requests require a valid Bearer token in the `Authorization` header.

***

## List Integrations

Return all integrations available to your workspace, optionally filtered by connection status or type.

**`GET https://api.google.com/v1/integrations`**

### Query Parameters

<ParamField query="status" type="string">
  Filter by connection status. Accepted values: `connected`, `available`.
</ParamField>

<ParamField query="type" type="string">
  Filter by integration type. Examples: `slack`, `github`, `zapier`.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://api.google.com/v1/integrations?status=connected" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "int_slack_01",
      "type": "slack",
      "name": "Slack",
      "status": "connected",
      "connected_at": "2024-02-01T09:00:00Z",
      "config": {
        "channel": "#notifications",
        "events": ["record.created", "record.updated"]
      }
    }
  ]
}
```

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the request completed successfully.
</ResponseField>

<ResponseField name="data" type="array">
  Array of integration objects matching the query.

  <Expandable title="Integration object">
    <ResponseField name="id" type="string">
      Unique identifier for this integration instance, prefixed with `int_`.
    </ResponseField>

    <ResponseField name="type" type="string">
      The integration provider type (e.g., `slack`, `github`, `zapier`).
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable display name for the integration.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current connection status: `connected` or `available`.
    </ResponseField>

    <ResponseField name="connected_at" type="string">
      ISO 8601 timestamp of when the integration was connected. `null` if not yet connected.
    </ResponseField>

    <ResponseField name="config" type="object">
      Integration-specific configuration settings, such as target channels, event subscriptions, or sync rules.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Get Integration

Fetch the full details and current configuration for a single integration by its unique ID.

**`GET https://api.google.com/v1/integrations/:id`**

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the integration to retrieve (e.g., `int_slack_01`).
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://api.google.com/v1/integrations/int_slack_01" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "int_slack_01",
    "type": "slack",
    "name": "Slack",
    "status": "connected",
    "connected_at": "2024-02-01T09:00:00Z",
    "config": {
      "channel": "#notifications",
      "events": ["record.created", "record.updated"]
    }
  }
}
```

***

## Connect Integration

Create a new integration connection for your workspace by specifying the integration type and its required configuration.

**`POST https://api.google.com/v1/integrations`**

### Body Parameters

<ParamField body="type" type="string" required>
  The integration type to connect. Examples: `slack`, `github`, `zapier`.
</ParamField>

<ParamField body="config" type="object" required>
  An object containing integration-specific configuration settings. The required keys vary by integration type — refer to each integration's documentation for the accepted fields.
</ParamField>

### Example Request — Connecting Slack

```bash theme={null}
curl -X POST "https://api.google.com/v1/integrations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slack",
    "config": {
      "channel": "#notifications",
      "events": ["record.created", "record.updated", "user.invited"],
      "bot_token": "xoxb-your-slack-bot-token"
    }
  }'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "int_slack_02",
    "type": "slack",
    "name": "Slack",
    "status": "connected",
    "connected_at": "2024-06-01T10:00:00Z",
    "config": {
      "channel": "#notifications",
      "events": ["record.created", "record.updated", "user.invited"]
    }
  }
}
```

<Note>
  Integrations that use OAuth for authentication (such as GitHub and Google Drive) cannot be fully connected through the API alone. You must complete the OAuth authorization flow in the Google web interface before their configuration becomes active. The API will return a `pending_auth` status for these integrations until authorization is complete.
</Note>

***

## Update Integration Config

Modify the configuration of an existing integration without disconnecting and reconnecting it. Only the fields you include are updated.

**`PATCH https://api.google.com/v1/integrations/:id`**

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the integration to update.
</ParamField>

### Body Parameters

<ParamField body="config" type="object" required>
  An object containing the configuration fields you want to update. For example, you can update the Slack channel target or change the list of subscribed events. Keys not included are preserved as-is.
</ParamField>

### Example Request

```bash theme={null}
curl -X PATCH "https://api.google.com/v1/integrations/int_slack_01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "channel": "#engineering-alerts",
      "events": ["record.created", "record.deleted", "user.removed"]
    }
  }'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "int_slack_01",
    "type": "slack",
    "name": "Slack",
    "status": "connected",
    "connected_at": "2024-02-01T09:00:00Z",
    "config": {
      "channel": "#engineering-alerts",
      "events": ["record.created", "record.deleted", "user.removed"]
    }
  }
}
```

<Tip>
  When updating event subscriptions, provide the complete desired list of events. The `events` array in `config` is fully replaced on each update, not appended to.
</Tip>

***

## Disconnect Integration

Remove an integration from your workspace, severing the connection to the third-party service.

**`DELETE https://api.google.com/v1/integrations/:id`**

<Warning>
  Disconnecting an integration is immediate. Any automated workflows, notifications, or sync jobs driven by this integration will stop functioning at the moment of disconnection. For Slack integrations, event notifications will stop. For GitHub integrations, code sync will be suspended. Reconnecting will require reconfiguring the integration and, for OAuth-based services, completing the authorization flow again.
</Warning>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the integration to disconnect.
</ParamField>

### Example Request

```bash theme={null}
curl -X DELETE "https://api.google.com/v1/integrations/int_slack_01" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A successful disconnection returns HTTP `204 No Content` with an empty body.

***

## Error Reference

<AccordionGroup>
  <Accordion title="400 Bad Request">
    The request body is missing required fields or contains an unrecognized integration `type`. Verify the payload and try again.
  </Accordion>

  <Accordion title="401 Unauthorized">
    Your API key is missing or invalid. Include a valid Bearer token in the `Authorization` header.
  </Accordion>

  <Accordion title="404 Not Found">
    No integration exists with the specified `id`. Confirm the ID using the List Integrations endpoint.
  </Accordion>

  <Accordion title="409 Conflict">
    An integration of this type is already connected to your workspace. Disconnect the existing integration before creating a new one of the same type.
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    The `config` object is missing required fields for the specified integration type, or contains invalid values.
  </Accordion>
</AccordionGroup>