Create, search, and manage connected 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 business. While a partner gains visibility across every connected account, businesses can only access their own customers.

You can only grant scopes to an account that's created through Moov's hosted onboarding process via the [Dashboard](https://docs.moov.io/guides/dashboard/accounts/onboarding-links/) or [API](https://docs.moov.io/api/moov-accounts/onboarding/). Additionally, only accounts created through hosted onboarding have access to their own Dashboard. Within the Dashboard, a business can view the customers you've shared with them.

## [Scopes](https://docs.moov.io/guides/accounts/connections/#scopes)

[Scopes](https://docs.moov.io/api/authentication/scopes/) specify what actions an account can take on Moov's platform. The following scopes can be shared by a partner with other accounts:

- `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](https://docs.moov.io/guides/accounts/connections/#share-a-connection)

Use the `POST` share account connection [endpoint](https://docs.moov.io/api/moov-accounts/accounts/share-connection/) to share scopes with an account and create a connection. This enables accounts to view their customers/connections on Moov's platform via the [API](https://docs.moov.io/api/moov-accounts/accounts/list-connections/). If the account is onboarded via [hosted onboarding](https://docs.moov.io/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.

Ask

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

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

## [View connections](https://docs.moov.io/guides/accounts/connections/#view-connections)

Use the `GET` list connected accounts [endpoint](https://docs.moov.io/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](https://docs.moov.io/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**.

Ask

```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.

Ask

```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"\
  }\
]
```

## [Hosted onboarding](https://docs.moov.io/guides/accounts/connections/#hosted-onboarding)

If you onboard an account through hosted onboarding (via the [Dashboard](https://docs.moov.io/guides/dashboard/accounts/onboarding-links/) or [API](https://docs.moov.io/guides/accounts/hosted-onboarding/)), you will also be able to grant scopes for yourself and the new account.