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

# Create Integration

> Connect a provider to your workspace. The credentials are tested live and stored encrypted

Connect a provider. The credentials are checked with a live test, then stored encrypted. Secrets are never returned.

Two results can come back with `201`:

* **Connected.** The live test passed. `status` is `connected`.
* **Stored with an error.** The request was valid, but the live test failed. `status` is `error` and `last_error` says why. Fix the credentials and run [Test integration](https://docs.60db.ai/api-reference/agents/test-integration.md), or update the fields.

Invalid input is refused with `400` or `422`, and nothing is stored.

A custom webhook also returns its `signing_secret` in this response, once. See [Custom webhooks](https://docs.60db.ai/features/agents-integrations.md#custom-webhooks).

## Request

### Headers

**Authorization** `string` *required*

Bearer token with your API key (scope `agents`)

**Content-Type** `string` *required*

application/json

### Body

**provider** `string` *required*

A provider key from the [catalog](https://docs.60db.ai/api-reference/agents/list-integration-catalog.md), such as `hubspot`, `mcp` or `webhook`

**name** `string`

1 to 64 characters, unique in the workspace. Defaults to the catalog name

**fields** `object` (default: \{})

The field values, keyed by each field's `key` from the catalog. Text values are up to 4,096 characters. A custom webhook also takes a JSON object for `parameters` and `body_template`. Unknown keys are refused. Required fields must be present. See [Connect an integration](https://docs.60db.ai/features/agents-integrations.md#connect-an-integration)

## Response

**201 Created** with the connection. The fields match [List integrations](https://docs.60db.ai/api-reference/agents/list-integrations.md).

```json theme={null}
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "provider": "hubspot",
    "name": "HubSpot (sales)",
    "status": "connected",
    "last_tested_at": "2026-11-12T09:30:00.000Z",
    "last_error": null,
    "created_by": "Asha Rao",
    "created_at": "2026-11-12T09:29:00.000Z",
    "config": {},
    "secret_hints": { "token": "…a9Qz" },
    "used_by": []
  }
}
```

For a custom webhook, the response also has `"signing_secret": "whsec_…"`. It is shown only here. For a custom webhook, `config` is `{ "actions": [...] }`. `used_by` lists the agents that hold the connection's tools. A new connection has none, so it is `[]`.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `VALIDATION_ERROR` | The body is invalid, a field is unknown, a required field is missing, or a field value is not valid. `field` is `fields.<key>` when a field is at fault |
| 403 | `POLICY_DENY` | Your role cannot manage integrations (owner, admin and developer only), or the API key lacks the `agents` scope |
| 404 | `INTEGRATION_PROVIDER_NOT_FOUND` | `provider` is not in the catalog |
| 409 | `INTEGRATION_NAME_TAKEN` | An integration with this name already exists |
| 422 | `INTEGRATION_PROVIDER_UNSUPPORTED` | The provider cannot be connected with a key here. Salesforce, Google Calendar and Google Drive need an app setup. Avaya uses a telephony guide. WhatsApp is set up in its own feature |
| 422 | `INTEGRATION_URL_REJECTED` | The URL is not public `https` on port 443, has credentials or a fragment, or points to a private address. `field` is `url`, or `fields.actions[<n>].url` for an action of a custom webhook |
| 429 | `RATE_LIMITED` | More than 10 integration changes in the last minute |
| 503 | `INTEGRATIONS_NOT_CONFIGURED` | Credential storage is not available on this server |

## Example

```bash cURL theme={null}
curl -X POST https://api.60db.ai/agents/integrations \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "hubspot",
    "name": "HubSpot (sales)",
    "fields": { "token": "pat-YOUR_TOKEN" }
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.