API Documentation V2

Lead Gen V2 Batch API

Lead Gen V2 is batch-first. Use the batch endpoints to create and process lead-gen mini sites.

Base URL:

https://www.1clickwebsite.ai

Use the www hostname for API requests. The bare domain redirects to www, and command-line clients such as curl do not follow that redirect unless explicitly configured with -L.

White-label agencies can replace this with their workspace domain, such as https://sites.example.com.

Authentication

Use an API key from your 1ClickWebsite account in the Authorization header.

Authorization: Bearer YOUR_API_KEY

White-label agencies should create an agency key under Settings → API Keys. The same 1cw_agency_... key works for both Lead Gen batch requests and agency site-creation requests.

Standard 1ClickWebsite accounts can continue using their existing account API keys. Every raw key is shown once and then stored as a secure hash.

Available Template Keys

Use the top-level templateKey field to choose the Lead Gen V2 template for the whole batch.

lightning is the current production Lead Gen V2 template. More template keys can be added later as new templates are converted.

Create A Batch

POST /api/lead-gen/batches

Creates a Lead Gen V2 batch and reserves credits.

Credit Rules

Agency API keys use the agency's saved OpenAI key and do not spend user lead-gen credits. Standard account API keys have a five-credit minimum per batch.

If the batch cannot be created, credits are not kept. If processing fails for a row, the batch item records the error status.

Request Body

Top-level fields:

Row fields:

Template selection is batch-level only. Do not send templateKey, template_key, templateName, or template_name inside individual rows.

Each row should include businessName or business_name. The older Google identifier format is still accepted temporarily; see the deprecated section below.

Example Request

curl -X POST "https://www.1clickwebsite.ai/api/lead-gen/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Roofing",
    "templateKey": "lightning",
    "primaryColor": "#0B1F3A",
    "backgroundTheme": "light",
    "logoSizePx": 96,
    "rows": [
      {
        "businessName": "RidgeLine Roofing",
        "phone": "(555) 010-0199",
        "address": "1480 Main St, Denver, CO 80202",
        "primaryColor": "#0B1F3A",
        "logoUrl": "https://placehold.co/360x120/0B1F3A/FFFFFF.png?text=RidgeLine+Roofing"
      },
      {
        "businessName": "Summit Shield Roofing",
        "email": "hello@summitshieldroofing.com",
        "address": "Austin, TX",
        "primaryColor": "#5B1117",
        "logoUrl": "https://placehold.co/360x120/5B1117/FFFFFF.png?text=Summit+Shield"
      },
      {
        "businessName": "Northstar Roofing",
        "phone": "(555) 010-0164",
        "email": "hello@northstarroofing.com",
        "address": "London",
        "primaryColor": "#0F3B2E"
      }
    ]
  }'

Example Response

{
  "ok": true,
  "batchId": "24fc4b0b-d1e2-4320-b822-5bb39c4437bf",
  "batch": {
    "id": "24fc4b0b-d1e2-4320-b822-5bb39c4437bf",
    "status": "pending",
    "industry": "Roofing",
    "template_key": "lightning",
    "total_count": 3,
    "credits_reserved": 5
  },
  "creditsReserved": 5,
  "creditsRemaining": 42
}

Deprecated Google Identifier Row Format

The older google_cid and google_place_id row format is still accepted for existing integrations, but it is deprecated and scheduled for removal on July 7, 2026.

Prefer the businessName / business_name format shown above for all new integrations.

Deprecated row fields:

Deprecated example:

{
  "industry": "Roofing",
  "templateKey": "lightning",
  "rows": [
    {
      "google_cid": "12345678901234567890"
    },
    {
      "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4"
    }
  ]
}

If a row includes both a business name and a Google identifier, the Google identifier is still stored and may be used for enrichment. Do not send both google_cid and google_place_id on the same row.

Update Batch Settings

PATCH /api/lead-gen/batches/{batchId}

Updates one or more design defaults for an existing batch. Send at least one supported setting.

Each setting is applied independently. Rows still using that batch default are updated immediately, while rows with an individual override for that setting are left unchanged.

Request Body

The camelCase and snake_case names are aliases. Do not send both versions of the same setting in one request.

Example request:

curl -X PATCH "https://www.1clickwebsite.ai/api/lead-gen/batches/24fc4b0b-d1e2-4320-b822-5bb39c4437bf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#173B57",
    "backgroundTheme": "dark",
    "logoSizePx": 104
  }'

Example response:

{
  "ok": true,
  "batchId": "24fc4b0b-d1e2-4320-b822-5bb39c4437bf",
  "primaryColor": "#173B57",
  "backgroundTheme": "dark",
  "logoSizePx": 104,
  "updatedCount": 30,
  "logoUpdatedCount": 28,
  "logoSkippedCount": 2,
  "colorUpdatedCount": 29,
  "colorSkippedCount": 1,
  "backgroundUpdatedCount": 27,
  "backgroundSkippedCount": 3
}

updatedCount is the number of unique rows changed by at least one submitted setting. The per-setting counts show how many rows inherited that default and how many retained an individual override.

Confirm A Batch Is Queued

POST /api/lead-gen/batches/{batchId}/process

This compatibility endpoint confirms the batch is queued. The dedicated Lead Gen worker owns all processing.

Example response:

{
  "ok": true,
  "batchId": "24fc4b0b-d1e2-4320-b822-5bb39c4437bf",
  "queued": true,
  "status": "queued",
  "message": "The dedicated Lead Gen worker owns batch processing."
}

Get A Batch

GET /api/lead-gen/batches/{batchId}

Returns the batch plus its items. Completed items include the generated public URL and saved site state.

Example response shape:

{
  "ok": true,
  "batch": {
    "id": "24fc4b0b-d1e2-4320-b822-5bb39c4437bf",
    "status": "completed",
    "industry": "Roofing",
    "credits_reserved": 5
  },
  "items": [
    {
      "id": "9578efdb-2c93-44bd-8e11-e1a99e25fb3f",
      "status": "completed",
      "business_name": "RidgeLine Roofing",
      "public_url": "https://lg.temphost024.com/lead-gen/ridgeline-roofing",
      "primary_color": "#0B1F3A",
      "logo_url": "https://placehold.co/360x120/0B1F3A/FFFFFF.png?text=RidgeLine+Roofing",
      "template_key": "lightning"
    }
  ]
}

List Batches

GET /api/lead-gen/batches

Returns recent Lead Gen V2 batches for the authenticated account.

Errors

Common error responses:

Error response shape:

{
  "ok": false,
  "error": "Invalid lead-gen batch rows",
  "details": [
    "Row 1 must include business_name."
  ]
}

Notes

• Use templateKey: "lightning" for the current Lead Gen V2 design.
• Template selection is top-level only. Row-level template fields are not supported.
• Numeric template IDs are not part of the public Lead Gen V2 API.
• Use row-level primaryColor when each generated site needs a different brand color.
• Use row-level logoUrl when a CSV or API request includes a business-specific logo.
• If logoUrl is empty, Lightning shows the default placeholder logo.
• Use top-level primaryColor, backgroundTheme, and logoSizePx to set the starting defaults for the whole batch.
• Use PATCH /api/lead-gen/batches/{batchId} to change any combination of those batch defaults later.
• Batch-setting updates do not replace individual color, background-mode, or logo-size overrides.
• phone, email, and address are optional.
• address can be a full street address, city/state, or a broad service area.
• The batch service set is shared across every row in the batch.
• Public hosted URLs may require deployment/sync depending on the current environment. Local development URLs can be used for preview testing.