> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fullenrich.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-accounts

> Create isolated API scopes within a FullEnrich workspace.

Sub-accounts let you separate API activity within a workspace. Each sub-account has its own identifier. Attach it to a request to keep the enrichments of the sub-account separate from direct workspace activity.

All sub-accounts use the credit balance of the workspace. A sub-account has no balance of its own.

> [!NOTE]
>
> Sub-accounts are in beta.

## Manage sub-accounts

Use the sub-account endpoints to create, list, retrieve, rename, archive, or restore sub-accounts.

Management requests always run at the workspace level. Authenticate with the workspace API key and **do not send** the `Sub-Account-ID` header when calling `/sub-accounts` endpoints.

> [card] [Create a sub-account](https://docs.fullenrich.com/api/v2/sub-accounts/create.md)
>
> Create a new isolated API scope.

> [card] [List sub-accounts](https://docs.fullenrich.com/api/v2/sub-accounts/list.md)
>
> List active sub-accounts or include archived ones.

> [card] [Get a sub-account](https://docs.fullenrich.com/api/v2/sub-accounts/get.md)
>
> Retrieve one sub-account by ID.

> [card] [Update a sub-account](https://docs.fullenrich.com/api/v2/sub-accounts/update.md)
>
> Rename, archive, or restore a sub-account.

## Make requests for a sub-account

Authenticate with the workspace API key and add the `Sub-Account-ID` header:

```http theme={null}
Authorization: Bearer <YOUR_API_KEY>
Sub-Account-ID: 70ff6a88-6291-417d-b6cd-04f1ca123470
```

These endpoints run in the scope of the sub-account:

| Endpoint | Effect of `Sub-Account-ID` |
| - | - |
| [`POST /contact/enrich/bulk`](https://docs.fullenrich.com/api/v2/contact/enrich/bulk/post) | The enrichment belongs to the sub-account. |
| [`GET /contact/enrich/bulk/{enrichment_id}`](https://docs.fullenrich.com/api/v2/contact/enrich/bulk/get) | Returns only an enrichment of the sub-account. |
| [`POST /contact/reverse/email/bulk`](https://docs.fullenrich.com/api/v2/contact/reverse/email/bulk/post) | The reverse lookup belongs to the sub-account. |
| [`GET /contact/reverse/email/bulk/{enrichment_id}`](https://docs.fullenrich.com/api/v2/contact/reverse/email/bulk/get) | Returns only a reverse lookup of the sub-account. |
| [`/providers` endpoints](https://docs.fullenrich.com/api/v2/providers/overview#sub-accounts) | Manage the BYOK keys of the sub-account. |

Read a result with the same scope you used to create it. An enrichment created for a sub-account returns `404` without its `Sub-Account-ID`. An enrichment created without the header returns `404` with it.

The other endpoints, such as search and `GET /account/credits`, run at the workspace level. They still check the header when you send it.

Calls made without `Sub-Account-ID` remain direct workspace calls. An archived sub-account accepts `GET` requests and rejects all other requests.

> [!WARNING]
>
> Do not send `Sub-Account-ID` when creating, listing, retrieving, or updating sub-accounts. These management endpoints require the direct workspace scope.

### Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `error.sub_account.header_invalid` | `Sub-Account-ID` is not a valid UUID. |
| `404` | `error.sub_account.not_found` | The sub-account does not exist in the workspace. |
| `404` | `error.sub_account.archived` | The sub-account is archived and the request is not a `GET`. |
| `500` | `error.sub_account.resolve_failed` | FullEnrich could not read the sub-account. Try again later. |

## Webhooks for a sub-account

When an enrichment runs for a sub-account, every [webhook](https://docs.fullenrich.com/api/v2/general/webhooks.md) call for this enrichment includes the `Sub-Account-ID` header with the sub-account ID. Use it to route the results to the correct sub-account. Webhook calls for direct workspace enrichments do not include this header.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.