{
  "openapi": "3.1.0",
  "info": {
    "title": "Unlist.ai API",
    "version": "1.0.0",
    "description": "AI-powered data broker removal API. Scan any person's exposure across 500+ data broker sites, get an AI risk score, and submit opt-out requests automatically.\n\n**Base URL:** `https://unlist.ai/api/v1`\n\n**Authentication:** Bearer token in Authorization header\n\n**Get started:** https://unlist.ai/developers"
  },
  "servers": [{ "url": "https://unlist.ai/api/v1" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your API key from https://unlist.ai/developers"
      }
    },
    "schemas": {
      "Finding": {
        "type": "object",
        "properties": {
          "broker": { "type": "string", "example": "Spokeo" },
          "broker_slug": { "type": "string", "example": "spokeo" },
          "risk_score": { "type": "integer", "minimum": 0, "maximum": 100 },
          "risk_level": { "type": "string", "enum": ["high", "medium", "low"] },
          "fields_exposed": { "type": "array", "items": { "type": "string" } },
          "threats": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": { "type": "string", "enum": ["physical_safety", "identity_theft", "social_engineering", "reputation", "spam"] },
                "severity": { "type": "string", "enum": ["high", "medium", "low"] },
                "reason": { "type": "string" }
              }
            }
          },
          "opt_out_url": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/scan": {
      "get": {
        "summary": "Scan data broker exposure",
        "description": "Scans all major people-search sites and B2B sales databases for a person's information. Returns an AI risk score, ranked findings, and threat analysis.",
        "parameters": [
          { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Jane Smith", "description": "Full name of the person to scan" },
          { "name": "email", "in": "query", "schema": { "type": "string" }, "example": "jane@company.com", "description": "Email address — enables B2B database scanning (Apollo, ZoomInfo, Hunter)" },
          { "name": "city", "in": "query", "schema": { "type": "string" }, "example": "Austin" },
          { "name": "state", "in": "query", "schema": { "type": "string" }, "example": "TX" }
        ],
        "responses": {
          "200": {
            "description": "Scan results",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "risk_score": 74,
                  "risk_level": "high",
                  "ai_summary": "Found 5 listings. Spokeo and Radaris expose home address + employer — physical safety risk. Recommend immediate removal.",
                  "findings": [
                    {
                      "broker": "Spokeo",
                      "broker_slug": "spokeo",
                      "risk_score": 95,
                      "risk_level": "high",
                      "fields_exposed": ["Home address", "Phone number", "Employer", "Relatives"],
                      "threats": [{ "type": "physical_safety", "severity": "high", "reason": "Home address + employer exposed together" }],
                      "opt_out_url": "https://unlist.ai/remove/spokeo"
                    }
                  ],
                  "counts": { "total": 5, "high": 2, "medium": 2, "low": 1 },
                  "tokens_used": 9,
                  "tokens_remaining": 191
                }
              }
            }
          },
          "402": { "description": "Insufficient tokens" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/remove": {
      "post": {
        "summary": "Submit opt-out removal requests",
        "description": "Queue automated opt-out submissions to one or more data brokers. Uses 2 tokens per broker. Most removals complete within 1-7 days.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "brokers"],
                "properties": {
                  "name": { "type": "string", "example": "Jane Smith" },
                  "email": { "type": "string", "example": "jane@example.com" },
                  "brokers": {
                    "type": "array",
                    "items": { "type": "string" },
                    "example": ["spokeo", "whitepages", "radaris", "zoominfo"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Removals queued",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "job_id": "a1b2c3d4-...",
                  "queued": 4,
                  "tokens_used": 8,
                  "tokens_remaining": 183,
                  "status_url": "https://unlist.ai/api/v1/status?email=jane%40example.com",
                  "message": "4 opt-out requests queued. Most complete within 1-7 days."
                }
              }
            }
          }
        }
      }
    },
    "/status": {
      "get": {
        "summary": "Check removal status and token balance",
        "parameters": [
          { "name": "email", "in": "query", "schema": { "type": "string" }, "description": "Email to check status for (defaults to API key owner)" }
        ],
        "responses": {
          "200": {
            "description": "Status and balance",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "token_balance": 183,
                  "summary": { "total": 4, "confirmed": 2, "submitted": 1, "pending": 1, "failed": 0 },
                  "removals": [
                    { "broker": "spokeo", "status": "confirmed", "confirmed_at": "2026-04-07T10:23:00Z" },
                    { "broker": "whitepages", "status": "submitted", "submitted_at": "2026-04-06T18:00:00Z" }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}