---
title: "Create a BYOK key"
method: POST
path: "/providers"
---

# Create a BYOK key

`POST /providers`

## Request

- Base URL: `https://app.fullenrich.com/api/v2`
- URL: `https://app.fullenrich.com/api/v2/providers`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/fullenrich/apis/fullenrich-api-documentation/docs/providers/post.ts> (a function with typed inputs; its response is checked against the schema)

Register your own credentials for one data provider. FullEnrich checks the credentials with the provider before it saves them. The key applies to the workspace, or to the sub-account named in the Sub-Account-ID header.

## Headers

- `Sub-Account-ID` string, uuid

## Request body

- CreateBYOKKeyRequest
  - `provider` 'prospeo' | 'enrow' | 'cleon1' | 'datagma' | 'aviato' | 'wiza' | 'forager_ai' | 'icypeas' | 'contact_out' | 'people_data_labs' | 'lusha' | 'apollo_io' | 'zoominfo' | 'cognism', required: Provider identifier. Case-insensitive in requests; responses use lowercase.
  - `credentials` ProviderCredentials, required: Credentials for one provider. Send the complete set for the provider.
    - `api_key` string: Required for every provider except zoominfo. Your API key for the provider.
    - `client_id` string: Required for zoominfo. The client ID of your ZoomInfo Standard App.
    - `client_secret` string: Required for zoominfo. The client secret of your ZoomInfo Standard App.
    - `account_id` string: Required for forager_ai. Your Forager account ID, as a string of digits.
    - `account_email` string, email: Required for icypeas. The email address of your Icypeas account.
    - `personal_email_api_key` string: Optional for contact_out. A separate key for personal emails. When omitted, api_key is used for personal emails.
  - `priority` integer, required: Order of the key in its zone. A lower value runs first.
  - `zone` 'front' | 'back' | 'auto': Where the key runs in the waterfall. front: before the FullEnrich providers. back: after them. auto: at the position of the same provider in the FullEnrich waterfall.
  - `data_types` ProviderDataType[]: Data types this key supplies. Each value must be supported by the provider, with no duplicate. Default: all data types the provider supports.
  - `verify` boolean: If true, FullEnrich verifies the values found with this key and consumes FullEnrich credits for valid values. If false, the values are returned with the UNVERIFIED status and consume no FullEnrich credit. Default: true.
  - `enabled` boolean: If false, the key is saved but not used in enrichments. Default: true.

## Response `201`

Created. The response contains the key without its credentials.

- BYOKKey
  - `id` string, uuid, required: The key ID.
  - `workspace_id` string, uuid, required: The workspace that owns the key.
  - `sub_account_id` string, uuid: The sub-account that owns the key. Omitted for a workspace key.
  - `provider` 'prospeo' | 'enrow' | 'cleon1' | 'datagma' | 'aviato' | 'wiza' | 'forager_ai' | 'icypeas' | 'contact_out' | 'people_data_labs' | 'lusha' | 'apollo_io' | 'zoominfo' | 'cognism', required: Provider identifier. Case-insensitive in requests; responses use lowercase.
  - `zone` 'front' | 'back' | 'auto', required: Where the key runs in the waterfall. front: before the FullEnrich providers. back: after them. auto: at the position of the same provider in the FullEnrich waterfall.
  - `priority` integer, required: Order of the key in its zone. A lower value runs first.
  - `data_types` ProviderDataType[], required: Data types this key supplies.
  - `verify` boolean, required: Whether FullEnrich verifies the values found with this key.
  - `enabled` boolean, required: Whether the key is used in enrichments.
  - `created_at` string, date-time, required: When the key was created.
  - `updated_at` string, date-time, required: When the key was last updated.

## Other responses

- `400`: Invalid request, or credentials rejected by the provider. Nothing is saved.
- `401`: Unauthorized
- `403`: BYOK is not enabled for the workspace
- `404`: The sub-account named in the header does not exist, or is archived for a write request
- `409`: A key already exists for this provider in the selected scope.
- `429`: Too Many Requests
- `503`: The provider did not answer the credential check. Nothing is saved. Try again later.

## Changes

- **2026-11-09** `b5bec9933c01`: 1 warning, 1 info
  - added the new `cognism` enum value to the `provider` response property for the response status `201`
  - added the new `cognism` enum value to the request property `provider`
- **2026-11-05** `9e5fe5ba0794`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fullenrich/apis/fullenrich-api-documentation/changes/providers/post.md)

---

[API](https://skmtc.dev/fullenrich/apis/fullenrich-api-documentation.md) - [All operations](https://skmtc.dev/fullenrich/apis/fullenrich-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/fullenrich/apis/fullenrich-api-documentation/revisions/b5bec9933c01?raw)