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

# Update a BYOK Key

> Change one or more settings of a key. Omitted fields keep their value. A null value resets zone, data_types, verify, or enabled to its default. New credentials are checked with the provider first.

Change one or more settings of a key.

* Send only the fields to change. Send at least one.
* To rotate credentials, send the complete `credentials` object. FullEnrich checks it with the provider before it saves it.
* The provider is set by the path and cannot change.
* To reset `zone`, `data_types`, `verify`, or `enabled` to its default, send `null`.


## OpenAPI

````yaml api/v2/reference/openapi.yaml POST /providers/{provider}
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/{provider}:
    parameters:
      - $ref: '#/components/parameters/ProviderPath'
    post:
      summary: Update a BYOK key
      description: >-
        Change one or more settings of a key. Omitted fields keep their value. A
        null value resets zone, data_types, verify, or enabled to its default.
        New credentials are checked with the provider first.
      operationId: updateBYOKKey
      parameters:
        - $ref: '#/components/parameters/SubAccountIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBYOKKeyRequest'
            examples:
              RotateCredentials:
                summary: Replace the credentials
                value:
                  credentials:
                    api_key: pk_live_your_new_prospeo_key
              Disable:
                summary: Disable the key
                value:
                  enabled: false
              MoveToBack:
                summary: Change placement
                value:
                  zone: back
                  priority: 50
              ResetDefaults:
                summary: Reset data_types and verify to their defaults
                value:
                  data_types: null
                  verify: null
      responses:
        '200':
          description: OK. The response contains the updated key without its credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BYOKKey'
        '400':
          description: >-
            Invalid request, or new credentials rejected by the provider.
            Nothing is saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateEmpty:
                  summary: No recognized field in the body
                  value:
                    code: error.provider_config.update_empty
                    message: At least one field is required for an update
                CredentialsRejected:
                  value:
                    code: error.provider_config.credentials_rejected
                    message: Provider rejected the credentials
                CredentialsRequired:
                  summary: credentials is null or incomplete
                  value:
                    code: error.provider_config.credentials_required
                    message: Complete credentials are required
                CredentialsInvalid:
                  value:
                    code: error.provider_config.credentials_invalid
                    message: >-
                      Credentials must match the provider's required fields and
                      format
                PriorityRequired:
                  summary: priority is null
                  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:
                  summary: Empty array, duplicate, or unsupported data type
                  value:
                    code: error.provider_config.data_types_invalid
                    message: >-
                      Data types must be nonempty, unique, and supported by the
                      provider
                ProviderUnsupported:
                  value:
                    code: error.provider_config.provider_unsupported
                    message: Provider is not supported for BYOK
                RequestInvalid:
                  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/BYOKKeyNotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          $ref: '#/components/responses/ProviderVerificationUnavailable'
      security:
        - BearerAuth: []
components:
  parameters:
    ProviderPath:
      name: provider
      in: path
      required: true
      description: Provider identifier. Case-insensitive.
      schema:
        $ref: '#/components/schemas/ProviderName'
      example: prospeo
    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:
    UpdateBYOKKeyRequest:
      type: object
      description: >-
        Send at least one field. Omit a field to keep its value. Set zone,
        data_types, verify, or enabled to null to reset its default. priority
        and credentials cannot be null.
      properties:
        credentials:
          $ref: '#/components/schemas/ProviderCredentials'
          description: >-
            Replaces the saved credentials in full. Send every required field of
            the provider. Masked values are not accepted. The new credentials
            are checked with the provider before they are saved.
        priority:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: Order of the key in its zone. A lower value runs first.
          example: 20
        zone:
          type:
            - string
            - 'null'
          enum:
            - front
            - back
            - auto
            - null
          description: Where the key runs in the waterfall. null resets to front.
          example: back
        data_types:
          type:
            - array
            - 'null'
          minItems: 1
          items:
            $ref: '#/components/schemas/ProviderDataType'
          description: >-
            Data types this key supplies. An empty array is invalid. null resets
            to all data types the provider supports.
          example:
            - contact.work_emails
        verify:
          type:
            - boolean
            - 'null'
          description: >-
            If true, FullEnrich verifies the values found with this key. null
            resets to true.
          example: false
        enabled:
          type:
            - boolean
            - 'null'
          description: If false, the key is not used in enrichments. null resets to true.
          example: false
    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
    ProviderDataType:
      type: string
      description: Data type a key can supply.
      enum:
        - contact.work_emails
        - contact.personal_emails
        - contact.phones
      example: contact.work_emails
    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
  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
    BYOKKeyNotFound:
      description: >-
        No key for this provider in the selected scope, or the sub-account named
        in the header does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            KeyNotFound:
              value:
                code: error.provider_config.not_found
                message: Provider configuration not found
            SubAccountNotFound:
              value:
                code: error.sub_account.not_found
                message: Sub-account not found
            SubAccountArchived:
              summary: Write request for an archived sub-account
              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.