---
title: "Create an integration connection"
method: POST
path: "/companies/{companyId}/integrations"
tags: ["Integrations"]
---

# Create an integration connection

`POST /companies/{companyId}/integrations`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/companies/{companyId}/integrations`
- Auth: HTTP bearer

## Request body

- CreateIntegrationConnectionInput
  - `provider` string, required
  - `category` string, required
  - `status` 'connected' | 'disconnected'
  - `entityId` string, uuid: Attach the connection to an authorized concrete legal entity (#1170). Omission is accepted only when the actor has exactly one authorized legal entity; ambiguous ownership fails validation.

## Response `201`

Integration connection created

- IntegrationConnectionResponse
  - `success` boolean
  - `data` IntegrationConnection
    - `id` string, uuid, required
    - `companyId` string, uuid, required
    - `provider` string, required
    - `category` string, required
    - `status` 'connected' | 'disconnected', required
    - `needsReauth` boolean: True when the provider requires the user to re-authorize before syncing can resume.
    - `awaitingOnboardingClassification` true: Present (true) only on an onboarding Plaid link held until the owner reviews its accounts; it reads `disconnected` and nothing syncs until that commit. Absent otherwise.
    - `lastSyncAt` string, date-time, nullable
    - `lastSyncAttemptAt` string, date-time, nullable: Stamped at the start of every sync attempt, successful or not.
    - `lastWebhookReceivedAt` string, date-time, nullable: Stamped when a matching provider webhook arrives.
    - `externalId` string, nullable: Provider's public account identifier (e.g. Stripe `acct_…`, Google Workspace account email). Not a credential — safe to expose to UI.
    - `entityId` string, uuid, required: Immutable concrete legal-entity owner (#1170). Consolidated/group ownership is forbidden.
    - `entityName` string, nullable: Convenience display name resolved from the persisted entityId.
    - `entityRole` string, nullable: Convenience display role resolved from the persisted entityId.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `422`: Validation error

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)