# Account connections

Create, search, and manage partner, merchant, and customer accounts on Moov's platform through scope sharing.

When you create additional accounts on Moov's platform, you share a connection with them. When those accounts, such as merchants processing payments, create accounts for their customers, they share a connection. As a partner, you're also connected to your merchants' customers.

- **Partner**: The top-level integrator account with visibility across all connected merchants and their customers
- **Merchant**: A business account, created by their Moov partner, that can manage its own customer base
- **Customer**: An end-user or buyer involved in a transfer on Moov's platform associated with one or more merchants

Moov maintains strict access controls when a partner shares scopes with a merchant. While a partner gains visibility across every connected account, merchants can only access their own customers.

Only merchants that are onboarded through Moov's [hosted onboarding](/guides/dashboard/accounts/onboarding-links/) process have access to the Dashboard. Within the Dashboard, merchants can view the customers you've shared with them.

## [Scopes](#scopes)

[Scopes](/api/authentication/scopes/) specify what actions an account can take on Moov's platform. The following scopes can be shared by a partner to their merchant:

- `accounts.read`
- `accounts.write`
- `analytics.read`
- `apple-pay-merchant.read`
- `apple-pay-merchant.write`
- `apple-pay.read`
- `apple-pay.write`
- `bank-accounts.read`
- `bank-accounts.write`
- `capabilities.read`
- `capabilities.write`
- `cards.read`
- `cards.write`
- `documents.read`
- `documents.write`
- `fed.read`
- `files.read`
- `files.write`
- `issued-cards.read`
- `issued-cards.write`
- `issued-cards.read-secure`
- `payment-methods.read`
- `ping.read`
- `profile-enrichment.read`
- `profile.read`
- `profile.write`
- `profile.disconnect`
- `representatives.read`
- `representatives.write`
- `transfers.read`
- `transfers.write`
- `wallets.read`

## [Share a connection](#share-a-connection)

Use the `POST` share account connection [endpoint](/api/moov-accounts/accounts/share-connection/) to share scopes with a merchant and create a connection. This enables merchants to view their customers/connections on Moov's platform via the [API](/api/moov-accounts/accounts/list-connections/). If the merchant is onboarded via [hosted onboarding](/guides/dashboard/accounts/onboarding-links/), they'll also be able to view their customers within the Dashboard.

The `principalAccountID` is the account ID of the Moov account that should receive access to the chosen scopes. If no scopes are provided in the request, all intersecting scopes are added.

```zsh
curl -X POST "https://api.moov.io/accounts/{accountID}/connections" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.04.00" \
  -d '{
  "principalAccountID": "c520f1b9-0ba7-42f5-b977-248cdbe41c69",
  "allowScopes": [ 
    "transfers.write", 
    "payment-methods.read"
  ]
}'
```

You cannot edit, add, or remove scopes once they have been selected and enabled.

## [View connections](#view-connections)

Use the `GET` list connected accounts [endpoint](/api/moov-accounts/accounts/list-connections/) to view connections. You can filter the results by using the following queries in the request:

| Query param           | Description                                                                                                                           |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| `name`                | Display name, legal business name, or an individual's first, middle, and last name                                                    |
| `email`               | Full email address                                                                                                                    |
| `type`                | Can be business or individual. If combined with `name`, the response will only include names for accounts with matching account type. |
| `foreignID`           | A foreign/external alias which can be used to reference a resource                                                                    |
| `includeDisconnected` | Disconnected accounts                                                                                                                 |
| `capability`          | Enabled capabilities. See [capability](/guides/accounts/capabilities/reference/) guide for all options.                               |
| `capabilityStatus`    | `enabled`, `disabled`, `pending`, `in-review`                                                                                         |

Additionally, you can choose to include a `skip` and `count` (default 200) parameter.

The request below is querying **business accounts** with a display name or legal business name of **Classbooker**.

```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/connected-accounts?name=classbooker&type=business" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.04.00"
```

The response will include information about the account.

```json
[
  {
    "mode": "production",
    "accountID": "53ca67ea-6fd3-423f-9544-ce2404159d33",
    "accountType": "business",
    "capabilities": [
      "transfers",
      "send-funds.rtp",
      "collect-funds.card-payments",
      "collect-funds.card-ach",
      "wallet"
    ],
    "customerSupport": {
      "email": "amanda@classbooker.dev"
    },
    "displayName": "Classbooker",
    "profile": {
      "business": {
        "legalBusinessName": "Classbooker",
        "ownersProvided": false
      }
    },
    "verification": {
      "verificationStatus": "unverified",
      "status": "unverified"
    },
    "settings": {
      "cardPayment": {
        "statementDescriptor": "Classbooker"
      },
      "achPayment": {
        "companyName": "Classbooker"
      }
    },
    "createdOn": "2024-12-16T17:55:20.557151867Z",
    "updatedOn": "2025-12-16T17:55:20.557151867Z"
  }
]
```