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

# Bring Your Own Key

> Use your own data provider accounts inside the FullEnrich waterfall.

With Bring Your Own Key (BYOK), you register the credentials of your own data provider accounts. FullEnrich then calls these providers with your credentials when it enriches your contacts.

* **Billing**: your provider bills your account for each call. Values found with your keys cost FullEnrich credits at a reduced rate, or no credit when you skip verification. See [Verification and credits](https://docs.fullenrich.com/api/v2/providers/verification-and-credits.md).
* **Fallback**: if a provider refuses your credentials, FullEnrich uses its own account for that provider, when it has one.
* **Security**: FullEnrich checks your credentials with the provider before it saves them, encrypts them at rest, and never returns them.

> [!NOTE]
>
> BYOK is in beta and is enabled on request. Contact [support@fullenrich.com](mailto:support@fullenrich.com) to enable it for your workspace.

## How it works

**1. Create a BYOK key**

Call [`POST /providers`](https://docs.fullenrich.com/api/v2/providers/create) with the provider name, your credentials, and a priority. See the [supported providers](https://docs.fullenrich.com/api/v2/providers/supported-providers.md) for the credentials each provider needs.

**2. Enrich contacts as usual**

Call [`POST /contact/enrich/bulk`](https://docs.fullenrich.com/api/v2/contact/enrich/bulk/post). The request does not change. FullEnrich places your keys in the waterfall by zone and priority.

**3. Read the results**

Each email and phone found with one of your keys carries the field `byok_provider`. See [What changes in your results](#what-changes-in-your-results).

## Manage BYOK keys

A BYOK key holds your credentials for one provider. A workspace has at most one key per provider.

> [card] [Create a BYOK key](https://docs.fullenrich.com/api/v2/providers/create.md)
>
> Register and check your credentials for one provider.

> [card] [List BYOK keys](https://docs.fullenrich.com/api/v2/providers/list.md)
>
> See every key, with masked credentials.

> [card] [Check a BYOK key](https://docs.fullenrich.com/api/v2/providers/status.md)
>
> Test the saved credentials with the provider.

> [card] [Update a BYOK key](https://docs.fullenrich.com/api/v2/providers/update.md)
>
> Rotate credentials, change the placement, or disable the key.

> [card] [Delete a BYOK key](https://docs.fullenrich.com/api/v2/providers/delete.md)
>
> Remove the key and its credentials.

> [card] [Errors](https://docs.fullenrich.com/api/v2/providers/errors.md)
>
> Status codes and error codes of the BYOK key endpoints.

## Placement in the waterfall

| Setting | Values | Effect |
| - | - | - |
| `zone` | `front`, `back`, `auto` | `front` runs your key before the FullEnrich providers. `back` runs it after them. `auto` runs it at the position of the same provider in the FullEnrich waterfall. Default: `front`. |
| `priority` | Integer from 1 | Orders your keys inside a zone. A lower value runs first. |
| `data_types` | `contact.work_emails`, `contact.personal_emails`, `contact.phones` | Limits the key to these data types. Default: all data types the provider supports. |

> [!WARNING]
>
> Use `auto` only for a provider that FullEnrich also uses for the same data types. Otherwise, `POST /contact/enrich/bulk` fails with `error.enrichment.byok.auto_position_missing`. If you are not sure, use `front` or `back`.

## What changes in your results

The enrichment request and the shape of the results do not change.

* A value found with one of your keys carries `byok_provider`, set to the `provider` of the key.
* A value served from the FullEnrich cache carries `from_cache: true`.
* A value found with a key that has `verify: false` has the status `UNVERIFIED`.

## Sub-accounts

Each [sub-account](https://docs.fullenrich.com/api/v2/sub-accounts/overview.md) has its own BYOK keys. To manage them, add the `Sub-Account-ID` header to any BYOK request:

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

During an enrichment for a sub-account, FullEnrich uses the key of the sub-account, or the workspace key when the sub-account has none.


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