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

# Create a BYOK Key

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

Register your credentials for one provider.

* FullEnrich checks the credentials with the provider before it saves them.
* One key per provider and per scope.
* See the [supported providers](https://docs.fullenrich.com/api/v2/providers/supported-providers.md) for the `provider` values and the credentials each one needs.


## OpenAPI

````yaml api/v2/reference/openapi.yaml POST /providers
openapi: 3.1.0
info:
  title: FullEnrich API Documentation
  version: 2.0.0
  description: >
    FullEnrich API enables you to enrich B2B contacts with emails and phone
    numbers using data from 20+ providers.


    We are GDPR and CCPA compliant.
servers:
  - url: https://app.fullenrich.com/api/v2
security: []
paths:
  /providers:
    post:
      summary: Create a BYOK key
      description: >-
        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.
      operationId: createBYOKKey
      parameters:
        - $ref: '#/components/parameters/SubAccountIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBYOKKeyRequest'
            examples:
              ApiKeyOnly:
                summary: API key only (most providers)
                value:
                  provider: prospeo
                  credentials:
                    api_key: pk_live_your_prospeo_key
                  priority: 10
                  zone: front
                  data_types:
                    - contact.work_emails
                    - contact.phones
                  verify: true
                  enabled: true
              ApiKeyAndAccountId:
                summary: API key and account ID (Forager)
                value:
                  provider: forager_ai
                  credentials:
                    api_key: your_forager_key
                    account_id: '48213'
                  priority: 20
              ApiKeyAndAccountEmail:
                summary: API key and account email (Icypeas)
                value:
                  provider: icypeas
                  credentials:
                    api_key: your_icypeas_key
                    account_email: ops@acme.com
                  priority: 30
                  data_types:
                    - contact.work_emails
              ApiKeyAndPersonalEmailKey:
                summary: API key and optional personal email key (ContactOut)
                value:
                  provider: contact_out
                  credentials:
                    api_key: your_contactout_key
                    personal_email_api_key: your_contactout_personal_email_key
                  priority: 40
                  zone: back
                  verify: false
              ClientCredentials:
                summary: Client ID and client secret (ZoomInfo)
                value:
                  provider: zoominfo
                  credentials:
                    client_id: your_zoominfo_client_id
                    client_secret: your_zoominfo_client_secret
                  priority: 50
      responses:
        '201':
          description: Created. The response contains the key without its credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BYOKKey'
        '400':
          description: >-
            Invalid request, or credentials rejected by the provider. Nothing is
            saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                CredentialsRejected:
                  summary: The provider refused the credentials
                  value:
                    code: error.provider_config.credentials_rejected
                    message: Provider rejected the credentials
                ProviderUnsupported:
                  value:
                    code: error.provider_config.provider_unsupported
                    message: Provider is not supported for BYOK
                CredentialsRequired:
                  value:
                    code: error.provider_config.credentials_required
                    message: Complete credentials are required
                CredentialsInvalid:
                  summary: Missing, unexpected, or malformed credential field
                  value:
                    code: error.provider_config.credentials_invalid
                    message: >-
                      Credentials must match the provider's required fields and
                      format
                PriorityRequired:
                  value:
                    code: error.provider_config.priority_required
                    message: Priority is required
                PriorityInvalid:
                  value:
                    code: error.provider_config.priority_invalid
                    message: Priority must be an integer between 1 and 2147483647
                ZoneInvalid:
                  value:
                    code: error.provider_config.zone_invalid
                    message: Zone must be front, back, or auto
                DataTypesInvalid:
                  value:
                    code: error.provider_config.data_types_invalid
                    message: >-
                      Data types must be nonempty, unique, and supported by the
                      provider
                RequestInvalid:
                  summary: The body is not valid JSON for this request
                  value:
                    code: error.provider_config.request_invalid
                    message: Unable to decode provider configuration request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BYOKKeyForbidden'
        '404':
          $ref: '#/components/responses/ScopedSubAccountNotFound'
        '409':
          description: A key already exists for this provider in the selected scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: error.provider_config.already_exists
                message: Provider configuration already exists
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          $ref: '#/components/responses/ProviderVerificationUnavailable'
      security:
        - BearerAuth: []
components:
  parameters:
    SubAccountIDHeader:
      name: Sub-Account-ID
      in: header
      required: false
      description: >-
        Manage the keys of one sub-account instead of the workspace keys. See
        the Sub-accounts section of the BYOK overview.
      schema:
        type: string
        format: uuid
      example: 70ff6a88-6291-417d-b6cd-04f1ca123470
  schemas:
    CreateBYOKKeyRequest:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ProviderName'
        credentials:
          $ref: '#/components/schemas/ProviderCredentials'
        priority:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: Order of the key in its zone. A lower value runs first.
          example: 10
        zone:
          $ref: '#/components/schemas/ProviderZone'
          description: 'Default: front.'
        data_types:
          type: array
          description: >-
            Data types this key supplies. Each value must be supported by the
            provider, with no duplicate. Default: all data types the provider
            supports.
          minItems: 1
          items:
            $ref: '#/components/schemas/ProviderDataType'
          example:
            - contact.work_emails
            - contact.phones
        verify:
          type: boolean
          description: >-
            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.
          example: true
        enabled:
          type: boolean
          description: >-
            If false, the key is saved but not used in enrichments. Default:
            true.
          example: true
      required:
        - provider
        - credentials
        - priority
    BYOKKey:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The key ID.
          example: 9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f
        workspace_id:
          type: string
          format: uuid
          description: The workspace that owns the key.
          example: 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
        sub_account_id:
          type: string
          format: uuid
          description: The sub-account that owns the key. Omitted for a workspace key.
          example: 70ff6a88-6291-417d-b6cd-04f1ca123470
        provider:
          $ref: '#/components/schemas/ProviderName'
        zone:
          $ref: '#/components/schemas/ProviderZone'
        priority:
          type: integer
          description: Order of the key in its zone. A lower value runs first.
          example: 10
        data_types:
          type: array
          description: Data types this key supplies.
          items:
            $ref: '#/components/schemas/ProviderDataType'
          example:
            - contact.work_emails
            - contact.phones
        verify:
          type: boolean
          description: Whether FullEnrich verifies the values found with this key.
          example: true
        enabled:
          type: boolean
          description: Whether the key is used in enrichments.
          example: true
        created_at:
          type: string
          format: date-time
          description: When the key was created.
          example: '2026-10-05T09:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the key was last updated.
          example: '2026-10-05T09:30:00Z'
      required:
        - id
        - workspace_id
        - provider
        - zone
        - priority
        - data_types
        - verify
        - enabled
        - created_at
        - updated_at
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
    ProviderName:
      type: string
      description: >-
        Provider identifier. Case-insensitive in requests; responses use
        lowercase.
      enum:
        - prospeo
        - enrow
        - cleon1
        - datagma
        - aviato
        - wiza
        - forager_ai
        - icypeas
        - contact_out
        - people_data_labs
        - lusha
        - apollo_io
        - zoominfo
      example: prospeo
    ProviderCredentials:
      type: object
      description: Credentials for one provider. Send the complete set for the provider.
      properties:
        api_key:
          type: string
          description: >-
            Required for every provider except zoominfo. Your API key for the
            provider.
          example: pk_live_your_provider_key
        client_id:
          type: string
          description: Required for zoominfo. The client ID of your ZoomInfo Standard App.
          example: your_zoominfo_client_id
        client_secret:
          type: string
          description: >-
            Required for zoominfo. The client secret of your ZoomInfo Standard
            App.
          example: your_zoominfo_client_secret
        account_id:
          type: string
          description: >-
            Required for forager_ai. Your Forager account ID, as a string of
            digits.
          example: '48213'
        account_email:
          type: string
          format: email
          description: Required for icypeas. The email address of your Icypeas account.
          example: ops@acme.com
        personal_email_api_key:
          type: string
          description: >-
            Optional for contact_out. A separate key for personal emails. When
            omitted, api_key is used for personal emails.
          example: your_contactout_personal_email_key
    ProviderZone:
      type: string
      description: >-
        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.
      enum:
        - front
        - back
        - auto
      example: front
    ProviderDataType:
      type: string
      description: Data type a key can supply.
      enum:
        - contact.work_emails
        - contact.personal_emails
        - contact.phones
      example: contact.work_emails
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            AuthorizationHeaderNotSet:
              value:
                code: error.authorization.not_set
                message: Authorization headers not set
            AuthorizationHeaderNotBearer:
              value:
                code: error.authorization.not_bearer
                message: Authorization headers do not have prefix 'bearer'
            UnknownApiKey:
              value:
                code: error.api.key
                message: Unknown api key
    BYOKKeyForbidden:
      description: BYOK is not enabled for the workspace
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: error.forbidden
            message: BYOK provider configuration is not enabled
    ScopedSubAccountNotFound:
      description: >-
        The sub-account named in the header does not exist, or is archived for a
        write request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            SubAccountNotFound:
              value:
                code: error.sub_account.not_found
                message: Sub-account not found
            SubAccountArchived:
              value:
                code: error.sub_account.archived
                message: Sub-account is archived
    RateLimitExceeded:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: error.rate.limit
            message: Too many requests. Try again in 1m
    ProviderVerificationUnavailable:
      description: >-
        The provider did not answer the credential check. Nothing is saved. Try
        again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: error.provider_config.verification_unavailable
            message: Unable to verify credentials with the provider
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string

````

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