---
title: "Connect an Integration"
method: POST
path: "/api/platform/v1/connections"
tags: ["data"]
---

# Connect an Integration

`POST /api/platform/v1/connections`

## Request

- Base URL: `https://docs.amdahl.ai`
- URL: `https://docs.amdahl.ai/api/platform/v1/connections`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Establish a new integration for a workspace, routing on the connector type: collect an API key, kick off an OAuth redirect, or track a social handle. Use when a user picks a provider from the catalog and wants it connected. Returns the created connection, or an OAuth authorize URL to redirect to. Creates and stores the connection without starting a sync.

## Request body

- object
  - `connector_type` string, required: Catalog connector type to connect (e.g. hubspot, fathom, twitter).
  - `name` string: Optional display label for this connection instance.
  - `scope` 'business' | 'personal': Ownership: business (workspace-wide) or personal. Defaults from the catalog.
  - `api_key` string: For api_key connectors: the API key / token to store (encrypted).
  - `api_id` string: For an api_key connector whose credential is a PAIR (today only Aircall, whose API is HTTP Basic): the non-secret id half, pasted alongside the token in api_key. Read connections.list_catalog to see whether a connector asks for it.
  - `base_url` string: For the computer_agent connector: its deployment base URL (http/https).
  - `account_handle` string: For social (handle) connectors: the resolved bare account handle.
  - `external_account_id` string: For social (handle) connectors: the provider's stable account id.
  - `display_name` string: For social (handle) connectors: display name snapshot.
  - `avatar_url` string: For social (handle) connectors: avatar image URL snapshot.
  - `followers` integer: For social (handle) connectors: follower count snapshot.
  - `return_to` string: For oauth connectors: console URL to redirect back to after the handshake (first-party origins only).
  - `call_filters` object: For an api_key CALLS connector (e.g. Fireflies): an optional atomic pre-sync call filter applied in the SAME request, so the source connects AND its filter decision lands together (an enabled filter syncs filtered; { enabled: false } is the "ingest all" opt-out). Omit to leave the calls source paused until a filter is set later. Own domains are stamped server-side. Requires workspace admin.
    - `enabled` boolean: Whether the filter is active. false = the "ingest all calls" opt-out.
    - `require_external` boolean: Ingest only calls with at least one external attendee.
    - `require_participants` string[]: Ingest only calls including at least one of these participant emails.
    - `exclude_participants` string[]: NEVER ingest a call one of these emails attended or hosted (exclusion wins over the include rules).
    - `exclude_domains` string[]: NEVER ingest a call with an attendee/host on one of these domains (suffix-aware; exclusion wins).
    - `internal_domains` string[]: Optional extra internal domains; the tenant own domains are merged in.
    - `bot_domains` string[]: Meeting-bot email domains to disregard when computing the roster.
    - `mode` 'strict': Fail-closed posture; only "strict".
    - `on_ambiguous` 'exclude': Ambiguity resolution; only "exclude".
  - `crm_recency` object: For a CRM connector (Salesforce / HubSpot / Pipedrive): how much activity/comms history (emails, meetings, calls, notes, tasks) the first sync imports. window_months (1–120) OR all_history. Reference records (accounts, contacts, deals) always land in full. Omit for the 12-month default.
    - `window_months` integer: Import the last N months of CRM activity/comms.
    - `all_history` boolean: Import ALL activity history (unbounded). Mutually exclusive with window_months.
  - `comms_filter` object: For a connector that supports it (HubSpot and Salesforce emails; Zero meetings, whose transcripts follow their meeting): a SOFT filter over which comms records (e.g. emails or meetings) the first sync imports — keep only external / rep-involved messages, dropping internal-only or irrelevant ones before they land. Applies only to the named comms streams; account/contact/deal records are untouched. Own domains stamped server-side. Omit to import comms unfiltered.
    - `enabled` boolean: Whether the filter is active.
    - `streams` string[]: Which comms streams to filter (e.g. ["emails"]).
    - `require_external` boolean: Keep only records with at least one external party.
    - `require_participants` string[]: Keep only records including at least one of these rep emails.
    - `exclude_participants` string[]: Always drop a record where one of these emails is a party.
    - `exclude_domains` string[]: Always drop a record with a party on one of these domains.
    - `internal_domains` string[]: Optional extra internal domains; the tenant own domains are merged in.
    - `on_ambiguous` 'include' | 'exclude': Ambiguity resolution; "include" (default) keeps a record when it cannot be judged.

## Response `200`

OK

- object
  - `data` unknown

## Other responses

- `400`: Invalid input - failed schema validation
- `401`: Authentication required
- `403`: Forbidden - missing scope or role
- `500`: Internal server error

---

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