openapi: 3.1.0
info:
  title: SkipScout API
  version: "1.0.0"
  summary: Skip tracing, property, business, and audience intelligence — as a REST API.
  description: |
    The **SkipScout API** lets any system — CRM, dialer, marketing platform, internal
    tool — embed real-time skip tracing and B2B / B2C intelligence with a single
    HTTPS request.

    ## What you can do

    - **Skip Trace** — find phones, emails, and current address for a person
    - **Property Lookup** — pull property, mortgage, and demographic data for a US address
    - **Business Lookup** — resolve a domain or business name into firmographics
    - **Person-to-Business** — match a consumer identity to their professional profile
    - **IP Lookup** — identify the business operating behind an IP address
    - **Email Validation** — score an email for deliverability
    - **Audience Estimate** — size a B2C or B2B audience matching any filter set (free)
    - **Audience Build** *(coming soon)* — produce a downloadable list with webhook delivery

    ## Pricing model

    Customers buy credits up front. Each successful lookup deducts 5 credits.
    Audience builds use tiered per-record pricing. **Estimates are always free.**
    See `/v1/account` for your current balance and `/v1/usage` for breakdown.

    ## SDKs and tooling

    - **OpenAPI 3.1 spec** — this document. Drop it into Postman, Insomnia, or any
      OpenAPI client generator (`openapi-generator-cli`) to scaffold a typed client
      in minutes.
    - **cURL, Node.js, Python, PHP** examples are linked from each endpoint below.
    - **Webhooks** — register a URL to receive `audience.completed` /
      `audience.failed` events with HMAC-SHA256 signatures.
  contact:
    name: SkipScout API Support
    email: info@skipscout.com
    url: https://skipscout.com/docs/api
  license:
    name: Commercial — SkipScout Terms of Service
    url: https://skipscout.com/terms

servers:
  - url: https://skipscout.com/api/v1
    description: Production

tags:
  - name: Account
    description: Account info, credit balance, usage.
  - name: Skip Trace
    description: Person → contact information.
  - name: Property
    description: Address → property, mortgage, demographic data.
  - name: Business
    description: Domain or business name → firmographic data.
  - name: Identity
    description: Consumer ↔ professional identity resolution.
  - name: Email
    description: Email deliverability and risk scoring.
  - name: Audiences
    description: B2C and B2B audience estimation and (coming soon) build-and-download.
  - name: Webhooks
    description: Async event delivery for long-running jobs.
  - name: Usage
    description: Per-key consumption reporting.

security:
  - bearerAuth: []

paths:

  /account:
    get:
      tags: [Account]
      summary: Get current account
      description: |
        Returns the authenticated account's name, email, credit balance, plan,
        and call counts for today + this month. **Free** — no credits charged.
      operationId: getAccount
      responses:
        "200":
          description: Account details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/Account"
              example:
                success: true
                data:
                  name: "John Smith"
                  email: "john@example.com"
                  credits: 1000
                  plan: "pay_as_you_go"
                  api_calls_today: 12
                  api_calls_this_month: 487
                meta:
                  credits_used: 0
                  credits_remaining: 1000
                  request_id: "req_abc123def456"
                  timestamp: "2026-05-01T22:30:00Z"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"

  /skip-trace:
    post:
      tags: [Skip Trace]
      summary: Look up contact info for a person
      description: |
        Returns phones, emails, and current address for a person.

        **Required input:** either an `email`, OR `first_name` + `last_name` +
        `address` + `city` + `state`.

        **Cost:** 5 credits per match. No-match returns `match: false` and
        charges nothing.
      operationId: skipTrace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SkipTraceRequest"
            examples:
              by_name_and_address:
                summary: Lookup by name + address
                value:
                  first_name: "John"
                  last_name: "Doe"
                  address: "123 Main St"
                  city: "Baltimore"
                  state: "MD"
                  zip: "21201"
              by_email:
                summary: Lookup by email
                value:
                  email: "john.doe@gmail.com"
      responses:
        "200":
          description: Lookup completed (may or may not have matched)
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/SkipTraceResult"
              examples:
                match:
                  summary: Match found (5 credits)
                  value:
                    success: true
                    data:
                      match: true
                      person:
                        first_name: "John"
                        last_name: "Doe"
                        phones:
                          - {number: "4105551234", type: "mobile", carrier: "Verizon"}
                        emails:
                          - {address: "john.doe@gmail.com", type: "personal"}
                        addresses:
                          - {street: "123 Main St", city: "Baltimore", state: "MD", zip: "21201", type: "current"}
                    meta:
                      credits_used: 5
                      credits_remaining: 995
                      request_id: "req_abc"
                      timestamp: "2026-05-01T22:31:00Z"
                no_match:
                  summary: No match (free)
                  value:
                    success: true
                    data:
                      match: false
                      person: null
                    meta:
                      credits_used: 0
                      credits_remaining: 1000
                      request_id: "req_abc"
                      timestamp: "2026-05-01T22:31:00Z"
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/InsufficientCredits"}
        "422": {$ref: "#/components/responses/ValidationError"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "502": {$ref: "#/components/responses/UpstreamError"}

  /property-lookup:
    post:
      tags: [Property]
      summary: Property, mortgage, and demographic data for an address
      description: |
        Pulls dwelling type, home value, mortgage details, occupant
        demographics, and household composition for a US residential address.

        **Required:** `address`, `city`, `state` (2-letter), `zip`.

        **Optional PII** (improves match quality and unlocks mortgage data):
        `first_name`, `last_name`, `email`, `phone`. Address-only requests
        return `match: false` with a hint in `meta.hint` — no upstream call,
        no credits charged. `meta.enrichment_path` is `"direct"` when PII
        was supplied or `"address_only_skipped"` when it was not.

        **Cost:** 2 credits per match (1 base skip-trace + 1 demographic
        surcharge; $0.15 each at the Tier 1 rate). No-match is free.
        Pricing matches the Scout AI CSV upload flow with the
        "+ Include property & mortgage data" checkbox enabled.
      operationId: propertyLookup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PropertyLookupRequest"
            example:
              address: "4321 NE 55th St"
              city: "Seattle"
              state: "WA"
              zip: "98105"
      responses:
        "200":
          description: Lookup completed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/PropertyLookupResult"
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/InsufficientCredits"}
        "422": {$ref: "#/components/responses/ValidationError"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "502": {$ref: "#/components/responses/UpstreamError"}

  /business-lookup:
    post:
      tags: [Business]
      summary: Look up a business by domain or name
      description: |
        Resolves a business by domain (preferred — most accurate) or by
        business_name + city + state. Returns name, domain, address,
        industry, employee count, revenue, and key contacts.

        **Required:** `domain`, OR `business_name` + `city` + `state`.

        **Cost:** 5 credits per match.
      operationId: businessLookup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BusinessLookupRequest"
            examples:
              by_domain:
                summary: By domain (recommended)
                value:
                  domain: "anthropic.com"
              by_name_and_location:
                summary: By name + city + state
                value:
                  business_name: "Acme Corp"
                  city: "Seattle"
                  state: "WA"
      responses:
        "200":
          description: Lookup completed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/BusinessLookupResult"
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/InsufficientCredits"}
        "422": {$ref: "#/components/responses/ValidationError"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "502": {$ref: "#/components/responses/UpstreamError"}

  /person-to-business:
    post:
      tags: [Identity]
      summary: Match a consumer identity to their business profile
      description: |
        Given a person's name + a consumer signal (personal email or
        LinkedIn URL), returns their professional title, employer,
        seniority, and business email.

        **Required:** `first_name` + `last_name` + (`email` OR `linkedin_url`).

        **Cost:** 5 credits per match.
      operationId: personToBusiness
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/P2BRequest"
            example:
              first_name: "Jane"
              last_name: "Smith"
              email: "jane.smith@gmail.com"
      responses:
        "200":
          description: Lookup completed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/P2BResult"
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/InsufficientCredits"}
        "422": {$ref: "#/components/responses/ValidationError"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "502": {$ref: "#/components/responses/UpstreamError"}

  /ip-lookup:
    post:
      tags: [Identity]
      summary: Identify the business behind an IP address
      description: |
        Returns the businesses operating from a public IPv4/IPv6 address.
        Private and reserved ranges return `match: false` for free.

        **Cost:** 5 credits per match.
      operationId: ipLookup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IpLookupRequest"
            example:
              ip: "8.8.8.8"
      responses:
        "200":
          description: Lookup completed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/IpLookupResult"
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/InsufficientCredits"}
        "422": {$ref: "#/components/responses/ValidationError"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "502": {$ref: "#/components/responses/UpstreamError"}

  /email/validate:
    post:
      tags: [Email]
      summary: Validate an email address
      description: |
        Returns deliverability, risk level, and disposable / role / spam-trap
        flags for an email.

        **Cost:** 5 credits per validation.
      operationId: emailValidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailValidationRequest"
            example:
              email: "support@stripe.com"
      responses:
        "200":
          description: Validation completed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/EmailValidationResult"
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/InsufficientCredits"}
        "422": {$ref: "#/components/responses/ValidationError"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "502": {$ref: "#/components/responses/UpstreamError"}

  /audiences/consumer/estimate:
    post:
      tags: [Audiences]
      summary: Estimate a B2C audience size (free)
      description: |
        Returns the estimated number of consumer records matching the supplied
        filters, along with a tiered cost quote and a redacted sample preview.

        **Cost:** 0 credits — always free.
      operationId: consumerEstimate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConsumerEstimateRequest"
            example:
              filters:
                state: ["WA"]
                own_rent: ["H"]
                age: "55-99"
              required_fields: ["address", "email"]
              include_demographics: true
      responses:
        "200":
          description: Estimate produced
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/AudienceEstimate"
        "401": {$ref: "#/components/responses/Unauthorized"}
        "422": {$ref: "#/components/responses/ValidationError"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "502": {$ref: "#/components/responses/UpstreamError"}

  /audiences/business/estimate:
    post:
      tags: [Audiences]
      summary: Estimate a B2B audience size (free)
      description: |
        Returns the estimated number of business contacts matching the
        supplied filters, with a tiered cost quote.

        **Cost:** 0 credits — always free.
      operationId: businessEstimate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BusinessEstimateRequest"
            example:
              filters:
                state: ["CA"]
                industry: ["Technology"]
                employee_count: "100-500"
              output: ["email"]
      responses:
        "200":
          description: Estimate produced
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/AudienceEstimate"
        "401": {$ref: "#/components/responses/Unauthorized"}
        "422": {$ref: "#/components/responses/ValidationError"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "502": {$ref: "#/components/responses/UpstreamError"}

  /audiences/consumer/build:
    post:
      tags: [Audiences]
      summary: Build a B2C audience list (coming soon)
      description: |
        Submits an asynchronous build job. Returns immediately with a
        `job_id` and `status_url`. Poll `/audiences/jobs/{jobId}` or
        register a webhook to be notified on completion.

        **Status: COMING SOON.** This endpoint currently returns 501.
        Use `/audiences/consumer/estimate` for sizing in the meantime.

        **Cost when live:** 1 credit per record, tiered USD pricing
        ($0.15 ≤ 10K, $0.13 10K–20K, $0.10 > 20K). 50,000-record cap.
      operationId: consumerBuild
      responses:
        "501":
          description: Coming soon
          content:
            application/json:
              schema: {$ref: "#/components/schemas/ErrorEnvelope"}

  /audiences/business/build:
    post:
      tags: [Audiences]
      summary: Build a B2B audience list (coming soon)
      description: |
        See `/audiences/consumer/build`. Same shape, business filters.
        **Status: COMING SOON.** Returns 501 today.
      operationId: businessBuild
      responses:
        "501":
          description: Coming soon
          content:
            application/json:
              schema: {$ref: "#/components/schemas/ErrorEnvelope"}

  /audiences/jobs/{jobId}:
    get:
      tags: [Audiences]
      summary: Check audience build job status
      description: Free. Returns processing / done / failed plus progress and download URL when ready.
      operationId: audienceJobStatus
      parameters:
        - name: jobId
          in: path
          required: true
          schema: {type: string, example: "job_abc123def456"}
      responses:
        "200":
          description: Job status
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/AudienceJob"
        "404": {$ref: "#/components/responses/NotFound"}

  /audiences/jobs/{jobId}/download:
    get:
      tags: [Audiences]
      summary: Download a completed audience as CSV or JSON
      description: Free. Default is CSV; pass `?format=json` for JSON array.
      operationId: audienceJobDownload
      parameters:
        - name: jobId
          in: path
          required: true
          schema: {type: string}
        - name: format
          in: query
          required: false
          schema: {type: string, enum: [csv, json], default: csv}
      responses:
        "200":
          description: Audience records
          content:
            text/csv:
              schema: {type: string, format: binary}
            application/json:
              schema:
                type: array
                items: {type: object, additionalProperties: true}
        "404": {$ref: "#/components/responses/NotFound"}

  /webhooks:
    post:
      tags: [Webhooks]
      summary: Register a webhook
      description: |
        Subscribe a URL to async events. Each delivery includes header
        `X-SkipScout-Signature: sha256=<HMAC_SHA256(raw_body, secret)>`.

        Allowed events: `audience.completed`, `audience.failed`.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookCreateRequest"
            example:
              url: "https://your-system.example.com/webhooks/skipscout"
              events: ["audience.completed", "audience.failed"]
              secret: "whsec_keep_this_safe"
      responses:
        "200":
          description: Webhook created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/Webhook"
        "422": {$ref: "#/components/responses/ValidationError"}
    get:
      tags: [Webhooks]
      summary: List your webhooks
      operationId: listWebhooks
      responses:
        "200":
          description: List of webhooks
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          webhooks:
                            type: array
                            items: {$ref: "#/components/schemas/Webhook"}

  /webhooks/{id}:
    delete:
      tags: [Webhooks]
      summary: Delete a webhook
      operationId: deleteWebhook
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: integer, example: 42}
      responses:
        "200":
          description: Webhook deleted
          content:
            application/json:
              schema: {$ref: "#/components/schemas/SuccessEnvelope"}
        "404": {$ref: "#/components/responses/NotFound"}

  /usage:
    get:
      tags: [Usage]
      summary: Usage breakdown by endpoint
      description: |
        Returns total request count and credit consumption for the chosen
        period, plus a per-endpoint breakdown. Free.
      operationId: getUsage
      parameters:
        - name: period
          in: query
          required: false
          schema:
            type: string
            enum: [today, this_month, last_30_days]
            default: this_month
      responses:
        "200":
          description: Usage details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/Usage"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      description: |
        Pass your API key as a Bearer token. Two key types:
        - `sk_live_*` — calls the real data network and consumes credits.
        - `sk_test_*` — returns deterministic mock data, charges no credits.
        Generate keys from your SkipScout account dashboard.

  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        Unique string (e.g., a UUID) the client generates per logical
        operation. A repeat request with the same key within 24 hours
        returns the original response without re-executing or re-charging.
      schema: {type: string, maxLength: 100, example: "idem_550e8400-e29b-41d4-a716"}

  responses:
    Unauthorized:
      description: API key missing, malformed, or revoked.
      content:
        application/json:
          schema: {$ref: "#/components/schemas/ErrorEnvelope"}
          example:
            success: false
            error: {code: "invalid_api_key", message: "API key is missing.", status: 401}
            meta: {request_id: "req_x", timestamp: "2026-05-01T22:30:00Z"}
    InsufficientCredits:
      description: Account balance is below the operation's cost.
      content:
        application/json:
          schema: {$ref: "#/components/schemas/ErrorEnvelope"}
    ValidationError:
      description: Input failed validation.
      content:
        application/json:
          schema: {$ref: "#/components/schemas/ErrorEnvelope"}
    RateLimited:
      description: Per-key rate limit hit. Honour the `Retry-After` header.
      headers:
        X-RateLimit-Limit:    {schema: {type: integer}}
        X-RateLimit-Remaining: {schema: {type: integer}}
        X-RateLimit-Reset:    {schema: {type: integer}}
        Retry-After:          {schema: {type: integer}}
      content:
        application/json:
          schema: {$ref: "#/components/schemas/ErrorEnvelope"}
    UpstreamError:
      description: Data network temporarily unavailable. Safe to retry with backoff.
      content:
        application/json:
          schema: {$ref: "#/components/schemas/ErrorEnvelope"}
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema: {$ref: "#/components/schemas/ErrorEnvelope"}

  schemas:
    SuccessEnvelope:
      type: object
      required: [success, data, meta]
      properties:
        success: {type: boolean, const: true}
        data:    {type: object, additionalProperties: true}
        meta:    {$ref: "#/components/schemas/Meta"}

    ErrorEnvelope:
      type: object
      required: [success, error, meta]
      properties:
        success: {type: boolean, const: false}
        error:   {$ref: "#/components/schemas/Error"}
        meta:    {$ref: "#/components/schemas/Meta"}

    Meta:
      type: object
      properties:
        credits_used:      {type: integer, example: 5}
        credits_remaining: {type: integer, example: 995}
        request_id:        {type: string, example: "req_abc123def456"}
        timestamp:         {type: string, format: date-time, example: "2026-05-01T22:30:00Z"}

    Error:
      type: object
      required: [code, message, status]
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - invalid_request
            - invalid_api_key
            - insufficient_credits
            - not_found
            - duplicate_request
            - validation_error
            - rate_limited
            - internal_error
            - upstream_error
            - service_unavailable
            - coming_soon
        message: {type: string}
        status:  {type: integer, example: 422}

    # ---- Account / Usage ----
    Account:
      type: object
      properties:
        name:                 {type: string}
        email:                {type: string, format: email}
        credits:              {type: integer}
        plan:                 {type: string, example: "pay_as_you_go"}
        api_calls_today:      {type: integer}
        api_calls_this_month: {type: integer}

    Usage:
      type: object
      properties:
        period:             {type: string, example: "this_month"}
        total_requests:     {type: integer}
        total_credits_used: {type: integer}
        breakdown:
          type: object
          additionalProperties:
            type: object
            properties:
              requests: {type: integer}
              credits:  {type: integer}
        credits_remaining: {type: integer}

    # ---- Skip Trace ----
    SkipTraceRequest:
      type: object
      properties:
        first_name: {type: string, maxLength: 100}
        last_name:  {type: string, maxLength: 100}
        address:    {type: string, maxLength: 200}
        city:       {type: string, maxLength: 100}
        state:      {type: string, minLength: 2, maxLength: 2, description: "2-letter US state"}
        zip:        {type: string, maxLength: 10}
        phone:      {type: string, maxLength: 20}
        email:      {type: string, format: email}
      description: |
        Provide *either* an `email`, OR `first_name` + `last_name` + `address`
        + `city` + `state`. Other fields improve match quality.

    SkipTraceResult:
      type: object
      properties:
        match: {type: boolean}
        person:
          oneOf:
            - {type: "null"}
            - $ref: "#/components/schemas/Person"

    Person:
      type: object
      properties:
        first_name: {type: string}
        last_name:  {type: string}
        phones:
          type: array
          items: {$ref: "#/components/schemas/Phone"}
        emails:
          type: array
          items: {$ref: "#/components/schemas/EmailRecord"}
        addresses:
          type: array
          items: {$ref: "#/components/schemas/Address"}

    Phone:
      type: object
      properties:
        number:  {type: string, example: "4105551234"}
        type:    {type: string, example: "mobile"}
        carrier: {type: string, example: "Verizon"}

    EmailRecord:
      type: object
      properties:
        address: {type: string, format: email}
        type:    {type: string, example: "personal"}

    Address:
      type: object
      properties:
        street: {type: string}
        city:   {type: string}
        state:  {type: string}
        zip:    {type: string}
        type:   {type: string, example: "current"}

    # ---- Property ----
    PropertyLookupRequest:
      type: object
      required: [address, city, state, zip]
      properties:
        address:    {type: string, maxLength: 200}
        city:       {type: string, maxLength: 100}
        state:      {type: string, minLength: 2, maxLength: 2}
        zip:        {type: string, maxLength: 10}
        first_name: {type: string, maxLength: 100, description: "Optional. Supplying PII unlocks mortgage and richer demographic fields. Address-only requests return match:false with a hint in meta.hint."}
        last_name:  {type: string, maxLength: 100}
        email:      {type: string, format: email, maxLength: 200}
        phone:      {type: string, maxLength: 20}

    PropertyLookupResult:
      type: object
      properties:
        match:    {type: boolean}
        property: {$ref: "#/components/schemas/Property"}
        mortgage: {$ref: "#/components/schemas/Mortgage"}
        occupant: {$ref: "#/components/schemas/Occupant"}
        household_composition:
          type: object
          additionalProperties: {type: boolean}
          description: |
            Yes/No flags about who's in the household. Possible keys:
            working_woman_in_household, senior_in_household, single_parent,
            presence_of_children, young_adult_in_household,
            small_office_or_home_office, online_purchasing_indicator,
            online_education.
        financial_indicators: {$ref: "#/components/schemas/FinancialIndicators"}
        vehicle:              {$ref: "#/components/schemas/Vehicle"}

    Property:
      type: object
      properties:
        dwelling_type:       {type: string, example: "Single Family Dwelling Unit"}
        home_value:          {type: string, example: "$500,000-749,999", description: "Estimated home value range"}
        home_market_value:   {type: integer, example: 554700, description: "Specific market value estimate in USD"}
        home_year_built:     {type: integer, example: 1966}
        home_purchase_date:  {type: string, example: "20031009", description: "YYYYMMDD format"}
        home_purchase_price: {type: string, example: "$175,000-199,999"}
        own_or_rent:         {type: string, example: "Own"}
        length_of_residence: {type: string, example: "15+ Years"}
        home_pool:           {type: boolean, example: false}

    Mortgage:
      type: object
      properties:
        amount:               {type: integer, example: 145000, description: "Primary mortgage purchase amount (USD)"}
        loan_type:            {type: string, example: "Conventional"}
        interest_rate:        {type: number, format: float, example: 3.75}
        rate_type:            {type: string, example: "Fixed"}
        purchase_date:        {type: string, example: "20031001", description: "YYYYMMDD"}
        loan_to_value:        {type: string, example: "60%"}
        second_amount:        {type: integer, example: 80000, description: "2nd most recent mortgage amount"}
        second_loan_type:     {type: string, example: "Conventional"}
        second_rate_type:     {type: string, example: "Fixed"}
        second_date:          {type: string, example: "20250624"}
        refinance_amount:     {type: integer, example: 256000}
        refinance_loan_type:  {type: string, example: "Conventional"}
        refinance_rate_type:  {type: string, example: "Fixed"}
        refinance_date:       {type: string, example: "20201121"}

    Occupant:
      type: object
      properties:
        age_range:              {type: string, example: "55-65"}
        age:                    {type: integer, example: 55}
        gender:                 {type: string, example: "Female"}
        dob:                    {type: string, example: "197009", description: "YYYYMM (no day)"}
        ethnic_group:           {type: string, example: "Hispanic"}
        religion:               {type: string, example: "Catholic"}
        education_level:        {type: string, example: "Completed College"}
        language:               {type: string, example: "English"}
        marital_status:         {type: string, example: "Single"}
        household_income:       {type: string, example: "$50,000-99,999"}
        net_worth:              {type: string, example: "$100,000-249,999"}
        credit_rating:          {type: string, example: "600-649"}
        occupation:             {type: string, example: "Craftsmen/Blue Collar"}
        individual_level_match: {type: boolean, example: true, description: "True when matched at the individual level (not just household)"}

    FinancialIndicators:
      type: object
      properties:
        credit_card_holder_bank: {type: boolean, example: true}
        upscale_card_holder:     {type: boolean, example: false}
        number_of_credit_lines:  {type: integer, example: 1}

    Vehicle:
      type: object
      properties:
        auto_year:  {type: integer, example: 2005}
        auto_make:  {type: string, example: "Chevrolet"}
        auto_model: {type: string, example: "TRAILBLAZER"}

    # ---- Business ----
    BusinessLookupRequest:
      type: object
      properties:
        domain:        {type: string, maxLength: 255}
        business_name: {type: string, maxLength: 255}
        address:       {type: string, maxLength: 200}
        city:          {type: string, maxLength: 100}
        state:         {type: string, minLength: 2, maxLength: 2}
        zip:           {type: string, maxLength: 10}

    BusinessLookupResult:
      type: object
      properties:
        match:    {type: boolean}
        business: {$ref: "#/components/schemas/Business"}

    Business:
      type: object
      properties:
        name:           {type: string}
        domain:         {type: string}
        address:        {type: string}
        phone:          {type: string}
        industry:       {type: string}
        sic_code:       {type: string}
        employee_count: {type: string, example: "100-249"}
        annual_revenue: {type: string, example: "$10M-$50M"}
        founded_year:   {type: integer}
        contacts:
          type: array
          items: {$ref: "#/components/schemas/BusinessContact"}

    BusinessContact:
      type: object
      properties:
        name:  {type: string}
        title: {type: string}
        email: {type: string, format: email}
        phone: {type: string}

    # ---- Person-to-Business ----
    P2BRequest:
      type: object
      required: [first_name, last_name]
      properties:
        first_name:   {type: string, maxLength: 100}
        last_name:    {type: string, maxLength: 100}
        email:        {type: string, format: email}
        linkedin_url: {type: string, maxLength: 255}

    P2BResult:
      type: object
      properties:
        match:        {type: boolean}
        professional: {$ref: "#/components/schemas/Professional"}

    Professional:
      type: object
      properties:
        first_name:     {type: string}
        last_name:      {type: string}
        title:          {type: string}
        department:     {type: string}
        seniority:      {type: string}
        business_email: {type: string, format: email}
        linkedin_url:   {type: string}
        company:        {$ref: "#/components/schemas/CompanyShort"}

    CompanyShort:
      type: object
      properties:
        name:           {type: string}
        domain:         {type: string}
        industry:       {type: string}
        employee_count: {type: string}
        annual_revenue: {type: string}

    # ---- IP ----
    IpLookupRequest:
      type: object
      required: [ip]
      properties:
        ip: {type: string, example: "8.8.8.8"}

    IpLookupResult:
      type: object
      properties:
        match: {type: boolean}
        domains:
          type: array
          items: {$ref: "#/components/schemas/IpDomain"}

    IpDomain:
      type: object
      properties:
        domain:         {type: string}
        business_name:  {type: string}
        industry:       {type: string}
        employee_count: {type: string}

    # ---- Email ----
    EmailValidationRequest:
      type: object
      required: [email]
      properties:
        email: {type: string, format: email}

    EmailValidationResult:
      type: object
      properties:
        email:                  {type: string, format: email}
        deliverable:            {type: boolean}
        risk_level:             {type: string, enum: [low, medium, high]}
        is_disposable:          {type: boolean}
        is_role_account:        {type: boolean}
        is_spam_trap:           {type: boolean}
        suggested_alternatives:
          type: array
          items: {type: string, format: email}

    # ---- Audiences ----
    ConsumerEstimateRequest:
      type: object
      required: [filters]
      properties:
        filters:
          type: object
          additionalProperties: true
          example:
            state: ["WA"]
            own_rent: ["H"]
            age: "55-99"
        required_fields:
          type: array
          items: {type: string, example: "address"}
        include_demographics: {type: boolean}

    BusinessEstimateRequest:
      type: object
      required: [filters]
      properties:
        filters:
          type: object
          additionalProperties: true
          example:
            state: ["CA"]
            industry: ["Technology"]
            employee_count: "100-500"
        output:
          type: array
          items: {type: string, example: "email"}

    AudienceEstimate:
      type: object
      properties:
        estimated_records: {type: integer, example: 15420}
        estimated_cost:
          type: object
          properties:
            credits: {type: integer, example: 15420}
            usd:     {type: string, example: "$2,313.00"}
            rate:    {type: string, example: "$0.15/record"}
        sample_preview:
          type: array
          items: {type: object, additionalProperties: true}

    AudienceJob:
      type: object
      properties:
        job_id:                       {type: string, example: "job_abc123def456"}
        status:                       {type: string, enum: [pending, processing, done, failed]}
        progress_percentage:          {type: integer, example: 65}
        estimated_seconds_remaining:  {type: integer, example: 120}
        records_delivered:            {type: integer}
        download_url:                 {type: string, example: "/api/v1/audiences/jobs/job_abc/download"}
        download_expires_at:          {type: string, format: date-time}
        credits_charged:              {type: integer}
        error_message:                {type: string}

    # ---- Webhooks ----
    WebhookCreateRequest:
      type: object
      required: [url, events]
      properties:
        url:    {type: string, format: uri, maxLength: 500}
        events:
          type: array
          minItems: 1
          items:
            type: string
            enum: [audience.completed, audience.failed]
        secret: {type: string, maxLength: 100, description: "Optional. If omitted, one is generated."}

    Webhook:
      type: object
      properties:
        webhook_id:    {type: integer}
        url:           {type: string, format: uri}
        events:
          type: array
          items: {type: string}
        status:        {type: string, enum: [active, disabled]}
        failure_count: {type: integer}
        created_at:    {type: string, format: date-time}