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

# Add waterfall to table

> Add a waterfall to a table by its UUID. A waterfall tries multiple data providers in sequence until one returns a result.

Use `GET /v1/waterfalls` to list available waterfalls and their parameters, enrichments, and email verifiers.

After adding, run the waterfall with `POST /v1/table/{uuid}/run-enrichment/{id}`.



## OpenAPI

````yaml POST /v1/table/{table_uuid}/add-waterfall
openapi: 3.1.0
info:
  title: Databar.ai API
  description: >-

    # Authentication


    Databar uses API keys to allow access to the API. You can find your API key
    in your workspace home page, but to use the REST API you’ll first need to
    schedule a call with us.

    Our API expects the API key to be included in all API requests to the server
    in the Header of your request with the key `x-apikey`.

    To find your API key, head over to your Databar workspace and click
    Integrations.


    **Example:**


    `bash

    curl https://api.databar.ai/v1/user/me -H x-apikey: {YOUR_API_KEY}`
  contact:
    email: info@databar.ai
  version: 0.1.2
servers:
  - url: https://api.databar.ai
    description: Production
security: []
paths:
  /v1/table/{table_uuid}/add-waterfall:
    post:
      tags:
        - Table
      summary: Add waterfall to table
      description: >-
        Add a waterfall to a table by its UUID. A waterfall tries multiple data
        providers in sequence until one returns a result.


        Use `GET /v1/waterfalls` to list available waterfalls and their
        parameters, enrichments, and email verifiers.


        After adding, run the waterfall with `POST
        /v1/table/{uuid}/run-enrichment/{id}`.
      operationId: Add_waterfall_to_table_v1_table__table_uuid__add_waterfall_post
      parameters:
        - name: table_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: The UUID of the table
            title: Table Uuid
          description: The UUID of the table
        - name: x-apikey
          in: header
          required: true
          schema:
            type: string
            title: API Key
            description: API Key for authentication
          description: API Key for authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddWaterfall'
            examples:
              email_getter:
                summary: Email finder waterfall
                description: Find emails using first name, last name and company columns.
                value:
                  waterfall: email_getter
                  enrichments:
                    - 833
                    - 966
                  mapping:
                    first_name: first_name
                    last_name: last_name
                    company: company
                  email_verifier: 10
              with_column_uuids:
                summary: Mapping with column UUIDs
                description: >-
                  Pass column identifier UUIDs from GET
                  /v1/table/{uuid}/columns.
                value:
                  waterfall: email_getter
                  enrichments:
                    - 833
                    - 966
                  mapping:
                    first_name: 42902e11-fa09-4abd-a627-77c07fc40cde
                    last_name: 53013f22-gb10-5bce-b738-88d18gd51def
                    company: 64124g33-hc21-6cdf-c849-99e29he62efg
      responses:
        '200':
          description: Waterfall added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddWaterfallResponse'
              example:
                id: 42
                waterfall_name: Email finder waterfall
        '400':
          description: Invalid request
          content:
            application/json:
              example:
                detail: Column 'company' not found in the table
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                detail: Not allowed
        '404':
          description: Table not found
          content:
            application/json:
              example:
                detail: Table not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AddWaterfall:
      properties:
        waterfall:
          type: string
          title: Waterfall
          description: >-
            Waterfall identifier (e.g. 'email_getter'). Get from GET
            /v1/waterfalls.
        enrichments:
          items:
            type: integer
          type: array
          minItems: 1
          title: Enrichments
          description: >-
            List of enrichment (provider) IDs to use in the waterfall cascade.
            Get available IDs from GET /v1/waterfalls/{identifier}.
        mapping:
          additionalProperties:
            type: string
          type: object
          title: Mapping
          description: >-
            Maps waterfall parameter names to table column identifiers (UUID) or
            column names (the key used in GET /v1/table/{uuid}/rows response).
            Get column identifiers from GET /v1/table/{uuid}/columns.
        email_verifier:
          anyOf:
            - type: integer
            - type: 'null'
          title: Email Verifier
          description: >-
            Optional enrichment ID for email verification (only for email
            waterfalls).
      type: object
      required:
        - waterfall
        - enrichments
        - mapping
      title: AddWaterfall
    AddWaterfallResponse:
      properties:
        id:
          type: integer
          title: Id
        waterfall_name:
          type: string
          title: Waterfall Name
      type: object
      required:
        - id
        - waterfall_name
      title: AddWaterfallResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````