{
  "openapi": "3.0.1",
  "info": {
    "title": "Waterfall Contact Enrichment — Email & Phone Lookup",
    "description": "Find business emails, phones, and social profiles from a name + company domain. Cascades through MX validation, website scraping, pattern detection, and SMTP verification. Free Clay alternative.",
    "version": "1.1",
    "x-build-id": "ZCyRhzLx8VarybAa3"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/ryanclinton~waterfall-contact-enrichment/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-ryanclinton-waterfall-contact-enrichment",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/ryanclinton~waterfall-contact-enrichment/runs": {
      "post": {
        "operationId": "runs-sync-ryanclinton-waterfall-contact-enrichment",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/ryanclinton~waterfall-contact-enrichment/run-sync": {
      "post": {
        "operationId": "run-sync-ryanclinton-waterfall-contact-enrichment",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "people"
        ],
        "properties": {
          "people": {
            "title": "People to enrich",
            "maxItems": 500,
            "type": "array",
            "description": "List of people to find contact info for. Each must have firstName + lastName + domain, OR fullName + domain, OR firstName + lastName + company (domain will be auto-resolved from company name).",
            "default": [
              {
                "firstName": "Jan",
                "lastName": "Curn",
                "domain": "apify.com"
              },
              {
                "firstName": "Satya",
                "lastName": "Nadella",
                "company": "Microsoft"
              }
            ]
          },
          "knownEmails": {
            "title": "Known emails (for pattern learning)",
            "maxItems": 100,
            "type": "array",
            "description": "Provide known email addresses from target domains. The actor learns the email pattern from these and applies it to all people at that domain. Format: [{\"email\": \"john.smith@company.com\", \"domain\": \"company.com\", \"name\": \"John Smith\"}]"
          },
          "enrichFromWebsite": {
            "title": "Enrich from website",
            "type": "boolean",
            "description": "Scrape the company website for emails, phones, and social links. Calls the Website Contact Scraper sub-actor.",
            "default": true
          },
          "detectPattern": {
            "title": "Detect email pattern",
            "type": "boolean",
            "description": "Detect the company's email pattern (e.g., first.last@domain). Calls the Email Pattern Finder sub-actor.",
            "default": true
          },
          "inferHierarchy": {
            "title": "Infer organizational hierarchy",
            "type": "boolean",
            "description": "When enriching multiple people at the same domain, detect seniority levels (C-suite, VP, Director, Manager) from job titles found on the company website. Results saved to key-value store under ORG_HIERARCHIES.",
            "default": false
          },
          "monitorJobChanges": {
            "title": "Monitor job changes",
            "type": "boolean",
            "description": "Compare current results against previous runs to detect job changes, title changes, and departures. Requires scheduled recurring runs. Changes saved to key-value store under JOB_CHANGES.",
            "default": false
          },
          "verificationLevel": {
            "title": "Verification level",
            "enum": [
              "standard",
              "deep"
            ],
            "type": "string",
            "description": "Standard: MX lookup only (fast). Deep: MX + SMTP verification per candidate (slower, more accurate).",
            "default": "standard"
          },
          "smtpTimeout": {
            "title": "SMTP timeout (seconds)",
            "minimum": 3,
            "maximum": 30,
            "type": "integer",
            "description": "Timeout for SMTP connections in deep mode. Higher values handle slow mail servers but increase run time.",
            "default": 10
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "How many people to process in parallel. Lower values are gentler on mail servers.",
            "default": 3
          },
          "outputProfile": {
            "title": "Output profile",
            "enum": [
              "minimal",
              "standard",
              "llm",
              "full"
            ],
            "type": "string",
            "description": "Controls how much data each result record contains. 'minimal' = decision-only (name, email, status, summary, recommendedAction, changeFlag). 'standard' = decision + extracted contact + sources. 'llm' = LLM-friendly subset with confidence + agentContract. 'full' = every field (default).",
            "default": "full"
          },
          "watchlistName": {
            "title": "Watchlist name (optional)",
            "type": "string",
            "description": "Name this run as a separate watchlist. Confidence history is stored per-watchlist, so the same actor runs as N independent enrichment lists (e.g. 'tier-1-prospects' vs 'churn-watch'). Leave blank to share the default history.",
            "default": ""
          },
          "monitorStateKey": {
            "title": "Monitor state key (alias for watchlistName)",
            "type": "string",
            "description": "Suite-aligned alias for watchlistName. Either input works; if both are set, watchlistName wins. Lets the same upstream orchestrator pass one consistent field name across waterfall, bulk-email-verifier, company-deep-research, and lead-enrichment-pipeline.",
            "default": ""
          },
          "lastAction": {
            "title": "Last action (optional, closes the feedback loop)",
            "type": "object",
            "description": "Tells the actor what action you took on this watchlist since the last run. On the next scheduled run, the actor compares the current state against the snapshot at action time and emits decisionMemory with an inferred outcome. Honest: only signal-change is observable — direct replies / off-platform engagement are not. Shape: { type: 'sent-outreach' | 'added-to-nurture' | 'archived' | string, takenAt: ISO date, note?: string }.",
            "default": {}
          },
          "webhookUrl": {
            "title": "Webhook URL (Slack or Discord)",
            "type": "string",
            "description": "Optional. Slack or Discord incoming webhook URL. On run completion, posts a rich embed with the top 10 enriched contacts + a link to the run. Auto-detects vendor by URL.",
            "default": ""
          },
          "circuitBreakerThreshold": {
            "title": "Circuit breaker threshold",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Abort the run if this many consecutive contacts produce a total enrichment failure (no domain or no MX). 0 disables. Recommended: 5-10 for batches over 100 contacts.",
            "default": 0
          },
          "includeAgentContract": {
            "title": "Include agentContract in output",
            "type": "boolean",
            "description": "Add a top-level agentContract { decision, confidence, nextAction, costToAct } to every record so MCP and AI-agent consumers don't have to traverse the full result.",
            "default": true
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}