Lead lists

Build targeted prospect lists from the technologies, keywords, and account attributes that match your market. Lead lists can include websites, company and contact details, social media profiles, and other enrichment data for prospecting, segmentation, and reporting.

Returns the lead lists you have created so you can monitor status, pricing, and available results.

GET https://api.wappalyzer.com/v2/lists/

Request

curl -H "x-api-key: <your api key>" "https://api.wappalyzer.com/v2/lists/"

Response

[
  {
    "id": "lst_abcdef",
    "createdAt": 1620687647,
    "status": "Ready",
    "totalCredits": 1000,
    "technologies": [
      {
        "slug": "shopify",
        "name": "Shopify",
        "categories": [
          {
            "slug": "ecommerce",
            "name": "Ecommerce"
          }
        ],
        "operator": "=",
        "version": null
      },
    ],
    "keywords": [],
    "rows": 1000
  }
]

Returns the full details of a list by its ID, including filters, pricing, download URLs, and field coverage once the list is ready.

GET https://api.wappalyzer.com/v2/lists/{id}

Request

curl -H "x-api-key: <your api key>" "https://api.wappalyzer.com/v2/lists/lst_abcdef"

Response

{
  "id": "lst_abcdef",
  "createdAt": 1620687647,
  "status": "Ready",
  "technologies": [
    {
      "slug": "shopify",
      "name": "Shopify",
      "categories": [
        {
          "slug": "ecommerce",
          "name": "Ecommerce"
        }
      ],
      "operator": "=",
      "version": null
    },
  ],
  "keywords": [ "FASHION" ],
  "languages": [ "en-us" ],
  "countries": [ "US" ],
  "industries": [ "Fashion & Apparel" ],
  "companySizes": [ "1,001-5,000 employees" ],
  "tlds": [ ".com" ],
  "matchCountryLanguage": false,
  "matchTechnologies": "or",
  "rootPath": false,
  "subset": 1000,
  "subsetSlice": 0,
  "subdomains": "include",
  "minAge": 0,
  "maxAge": 2,
  "fromDate": null,
  "requiredSets": [ "email" ],
  "excludeNoTraffic": false,
  "excludeMultilingual": false,
  "sets": [
    "email",
  ],
  "callbackUrl": "https://yourdomain/wappalyzer",
  "format": "csv",
  "totalCredits": 1000,
  "url": null,
  "sampleUrl": "https://lists.wappalyzer.com/wappalyzer-29ddddaa-4949-4217-86a7-f6a407e5853d-lst_abcdef-5ukjhs-sample.zip",
  "rows": {
    "shopify": 1000
  },
  "setRows": {
    "email": 1000,
  },
  "baseListId": "lst_abcdef"
}

Create a new lead list from technologies, keywords, and company filters. Use this endpoint to turn your ICP criteria into a downloadable prospect set.

POST https://api.wappalyzer.com/v2/lists

The initial response only includes the list ID and current status. Detailed fields such as totalCredits, sampleUrl, rows and setRows become available through the callback payload below or when fetching the list later.

Use a callback URL to continue your workflow as soon as a list is ready. List generation can take anywhere from a few seconds to a couple of hours depending on the query, so callbacks are the easiest way to avoid polling.

Request

curl -X POST -H "Content-Type: application/json" -H "x-api-key: <your api key>" "https://api.wappalyzer.com/v2/lists/" -d '{ "technologies": [ { "slug": "shopify" } ] }'

Response

{
  "id": "lst_abcdef",
  "status": "Calculating"
}

Callback response

Your callback URL receives a POST request when the list is ready to price and finalize.

{
  "id": "lst_abcdef",
  "status": "Ready",
  "rows": {
    "shopify": 1000
  },
  "setRows": {
    "email": 1000
  },
  "totalCredits": 1000,
  "sampleUrl": "https://lists.wappalyzer.com/wappalyzer-29ddddaa-4949-4217-86a7-f6a407e5853d-lst_abcdef-5ukjhs-sample.zip"
}

Exclude websites from your results using an uploaded suppression list or an existing lead list. Exclusions apply before the result limit, sample, export and credit calculation.

A suppression list is a reusable list of domains you want to exclude, such as existing customers. Upload it once and pass its suppressionListId when creating lead lists. To exclude websites from an existing lead list, use excludeListId. You can use both in the same request. Uploading and reusing a suppression list does not spend credits.

1. Upload the file in a single request. The response contains a reusable ID. No name or file size is required.
2. Fetch the ID every two seconds until its status is Ready. If it becomes Invalid, check the error message and correct the file.
3. Pass that ID as suppressionListId to POST /v2/lists. Continue with the usual sample review and list finalization. Reuse the same ID for subsequent lists.

You can also list all suppression lists, fetch a suppression list or delete a suppression list.

Use an uncompressed UTF-8 text file containing one domain or HTTP(S) URL per line, with no header. Blank lines are ignored. Domain matching ignores case and a leading www.; duplicates count once. Invalid lines reject the entire upload and report the line number. Files are never silently truncated.

Matching uses the existing lead-list subdomain rules. With subdomains: "include", an entry for example.com does not exclude every subdomain automatically. With subdomains: "merge", excluding the root domain also excludes the merged result for that domain.

These limits are shared by all API keys on the account. Storage is checked after upload and validation, using the size of the validated file. There is no storage reservation. Files that exceed the storage quota are rejected and removed. Original uploads and invalid files are removed after processing; interrupted uploads are scheduled for cleanup after 15 minutes. Background processing retries temporary failures for up to one hour; uploads that still cannot be processed become invalid and are cleaned up. Cleanup retries run every five minutes. Validated files remain available until deleted, and files retained for existing lead lists continue to count against storage.

Each upload creates a new ID for a fixed set of domains. To replace a suppression file, upload a new version and use its new ID in subsequent requests. Existing lead lists continue using their original set of domains. When combined with excludeListId, the existing combined limit of 500,000 exclusions still applies.

These fields are shared by the upload, fetch and deletion responses. File contents are not returned.

Uploads a file in one request, returning a reusable ID while validation runs in the background. Send the file itself as the request body with Content-Type: text/plain. No JSON wrapper, form fields or separate completion request are needed.

POST https://api.wappalyzer.com/v2/lists/suppressions

Required. An uncompressed UTF-8 text file of up to 20 MiB, with one domain or HTTP(S) URL per line and no header. See file format and matching. application/octet-stream is also accepted.

Returns 202 Accepted and the suppression list fields once the file is stored. Fetch the ID every two seconds while its status is Pending or Validating. Once it is Ready, the response includes domainCount and validated sizeBytes; pass the ID as suppressionListId when creating lead lists. If it becomes Invalid, read error and correct the file before uploading again. A fast validation may finish before the upload response arrives.

Files over 20 MiB return 413. Exceeding the daily or simultaneous upload limit returns 429. File-content errors and account-storage limits are checked in the background and reported with status Invalid and an error message.

The examples upload suppression.txt without a name or file size, then check its status until it is ready. The cURL example also uses jq to read the JSON responses. If polling stops before processing finishes, keep the ID and fetch its status later.

Request

api="https://api.wappalyzer.com/v2/lists/suppressions"
key="<your api key>"
result=$(curl --fail-with-body --max-time 75 -X POST \
  -H "Content-Type: text/plain" -H "x-api-key: $key" \
  --data-binary @suppression.txt "$api") || exit 1
id=$(printf '%s' "$result" | jq -r '.id')
echo "Suppression ID: $id"

for attempt in $(seq 1 60); do
  case $(printf '%s' "$result" | jq -r '.status') in
    Ready) printf '%s\n' "$result"; exit 0 ;;
    Pending|Validating) sleep 2 ;;
    *) printf '%s\n' "$result" >&2; exit 1 ;;
  esac
  result=$(curl --fail-with-body --max-time 30 \
    -H "x-api-key: $key" "$api/$id") || exit 1
done
echo "Still processing. Fetch $id again later."

Response

{
  "id": "sup_0123456789abcdef0123456789abcdef",
  "name": "sup_0123456789abcdef0123456789abcdef",
  "status": "Pending",
  "createdAt": 1792886400,
  "sizeBytes": 0
}

Returns up to 100 suppression lists per page, along with the storage allocation and limits shared by all API keys on your account.

GET https://api.wappalyzer.com/v2/lists/suppressions

Request

curl --fail-with-body -H "x-api-key: <your api key>" "https://api.wappalyzer.com/v2/lists/suppressions"

Response

{
  "lists": [
    {
      "id": "sup_0123456789abcdef0123456789abcdef",
      "name": "sup_0123456789abcdef0123456789abcdef",
      "status": "Ready",
      "createdAt": 1792886400,
      "domainCount": 2,
      "sizeBytes": 23
    }
  ],
  "nextCursor": null,
  "allocatedBytes": 23,
  "limits": {
    "fileBytes": 20971520,
    "domains": 250000,
    "accountBytes": 104857600,
    "uploadsPerDay": 20,
    "pendingUploads": 2,
    "uploadSeconds": 300,
    "activeUploadSeconds": 900,
    "abandonedSeconds": 86400
  }
}

Returns the status and metadata for one suppression list. Use this to check whether validation has completed.

GET https://api.wappalyzer.com/v2/lists/suppressions/{suppressionId}

Returns the suppression list fields.

Request

curl --fail-with-body -H "x-api-key: <your api key>" "https://api.wappalyzer.com/v2/lists/suppressions/sup_0123456789abcdef0123456789abcdef"

Response

{
  "id": "sup_0123456789abcdef0123456789abcdef",
  "name": "sup_0123456789abcdef0123456789abcdef",
  "status": "Ready",
  "createdAt": 1792886400,
  "domainCount": 2,
  "sizeBytes": 23
}

Retires the ID so it cannot be used in new lead-list requests. Existing lead lists and repeat jobs continue using their original set of excluded domains.

DELETE https://api.wappalyzer.com/v2/lists/suppressions/{suppressionId}

Returns the suppression list fields with status Retired, or Deleted if cleanup has already completed. Repeating deletion is safe while the record remains available.

Request

curl --fail-with-body -X DELETE -H "x-api-key: <your api key>" "https://api.wappalyzer.com/v2/lists/suppressions/sup_0123456789abcdef0123456789abcdef"

Response

{
  "id": "sup_0123456789abcdef0123456789abcdef",
  "name": "sup_0123456789abcdef0123456789abcdef",
  "status": "Retired",
  "createdAt": 1792886400,
  "domainCount": 2,
  "sizeBytes": 23,
  "retiredAt": 1792890000
}

Deletion does not immediately reclaim storage. Cleanup waits at least 24 hours and retains the file while lead lists reference it. Delete those lead lists to release their retained file. Cleanup is asynchronous; cleaned metadata expires after seven days.

When a list is ready, finalize it to spend credits and unlock the full download URL. After payment, the list status changes to Complete.

POST https://api.wappalyzer.com/v2/lists/{id}

Request

curl -X POST -H "Content-Type: application/json" -H "x-api-key: <your api key>" "https://api.wappalyzer.com/v2/lists/lst_abcdef" -d '{ "spendCredits": 1000 }'

Response

{
  "id": "lst_abcdef",
  "status": "Complete",
  "url": "https://lists.wappalyzer.com/wappalyzer-29ddddaa-4949-4217-86a7-f6a407e5853d-lst_abcdef-5ukjhs.zip",
}

Permanently delete a list you no longer need.

DELETE https://api.wappalyzer.com/v2/lists/{id}

Request

curl -X DELETE -H "x-api-key: <your api key>" "https://api.wappalyzer.com/v2/lists/lst_abcdef"

Response

{}