# `Codat.Platform.Connections`
[🔗](https://github.com/iamkanishka/codat.git/blob/v1.0.0/lib/codat/platform/connections.ex#L1)

Manage data connections between companies and their accounting/banking platforms.

A **connection** links a Codat company to a specific data source
(e.g., QuickBooks Online, Xero, Sage Intacct). Each company can have
multiple connections.

## Connection Statuses

| Status          | Description                                                   |
|-----------------|---------------------------------------------------------------|
| `Linked`        | Active, authorized connection. Data syncs can run.            |
| `Deauthorized`  | User revoked access. Must re-link to resume syncing.          |
| `Unlinked`      | Connection was manually disconnected from the Codat side.     |
| `PendingAuth`   | Authorization flow started but not yet completed.             |

## Re-authorization

When a connection becomes `Deauthorized`, redirect the user through the
Link flow again. Use `get_authorization_url/3` to get the redirect URL.
Do **not** create a new company for re-linking — it may incur additional usage costs.

## Example

    {:ok, page} = Codat.Platform.Connections.list(client, "company-id")
    connections = page.results

    linked = Enum.filter(connections, &(&1["status"] == "Linked"))

# `create`

```elixir
@spec create(Codat.Client.t() | String.t(), String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}
```

Creates a new data connection for a company.

## Parameters

- `platform_key` (**required**) — the integration key (e.g. `"gbol"` for QuickBooks Online).
  See [Codat integrations docs](https://docs.codat.io/integrations/accounting/overview)
  for all platform keys.

## Example

    {:ok, conn} = Codat.Platform.Connections.create(client, "company-id", "gbol")
    conn["status"]        # => "PendingAuth"
    conn["linkUrl"]       # => "https://link.codat.io/..."

# `delete`

```elixir
@spec delete(Codat.Client.t() | String.t(), String.t(), String.t() | keyword()) ::
  {:ok, nil} | {:error, Codat.Error.t()}
```

Deletes a data connection, removing it and all synced data.

Use `unlink/3` instead if you want to preserve synced data but stop future syncs.

# `get`

```elixir
@spec get(Codat.Client.t() | String.t(), String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}
```

Fetches a single connection by company ID and connection ID.

## Example

    {:ok, conn} = Codat.Platform.Connections.get(client, "company-id", "conn-id")
    conn["status"]  # => "Linked"
    conn["integrationKey"]  # => "gbol"  (QuickBooks Online)

# `get_authorization_url`

```elixir
@spec get_authorization_url(
  Codat.Client.t() | String.t(),
  String.t(),
  String.t() | keyword()
) ::
  {:ok, map()} | {:error, Codat.Error.t()}
```

Returns the authorization URL for re-linking a deauthorized connection.

## Example

    {:ok, %{"url" => url}} =
      Codat.Platform.Connections.get_authorization_url(client, "company-id", "conn-id")

# `list`

```elixir
@spec list(Codat.Client.t() | String.t(), String.t() | keyword(), keyword()) ::
  {:ok, Codat.Pagination.t()} | {:error, Codat.Error.t()}
```

Lists all data connections for a company.

## Options

- `:page`, `:page_size` — pagination
- `:query` — filter by status, e.g. `"status=Linked"`

## Example

    {:ok, page} = Codat.Platform.Connections.list(client, "company-id")
    {:ok, page} = Codat.Platform.Connections.list("company-id", query: "status=Linked")

# `unlink`

```elixir
@spec unlink(Codat.Client.t() | String.t(), String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}
```

Unlinks a connection without deleting it or its data.

Sets the connection status to `Unlinked`. The company and its historical data
are preserved. You can re-link by creating a new connection or redirecting
the user through Link.

## Example

    {:ok, conn} = Codat.Platform.Connections.unlink(client, "company-id", "conn-id")
    conn["status"]  # => "Unlinked"

---

*Consult [api-reference.md](api-reference.md) for complete listing*