# Thumbtack Pro Vetting & Hire Signal Scraper (`dataspryva/thumbtack-pro-vetting-and-hire-signal-scraper`) Actor

Search Thumbtack pros by category and city, browse a category nationwide, or fetch specific profiles, with rating, hire count, badges, response time and starting price for each pro.

- **URL**: https://apify.com/dataspryva/thumbtack-pro-vetting-and-hire-signal-scraper.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** Lead generation, Jobs, Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Thumbtack Pro Vetting & Hire Signal Scraper

Build a shortlist of Thumbtack service pros from public search pages and profile pages. Every record carries reputation and hiring signals: star rating, review volume, hires booked through Thumbtack, response speed, Top Pro status, background-check status, years in business and services offered.

### What it does

- **Search by category and location** — one city, or several `City, ST` locations supplied in the same run.
- **Browse a category nationwide** — sweeps major US cities and deduplicates pros seen in more than one market.
- **Fetch specific profile URLs** — paste Thumbtack profile links for deep vetting records.
- **Fetch category page URLs** — paste front-door links such as `https://www.thumbtack.com/tx/austin/plumbers`.
- **Paginate and filter** — four server-side sort orders, optional continuation across sort orders and nearby cities, and filters for rating, reviews, hires, Top Pro, instant booking and background-check status.

### Output fields

| Field | Description |
| --- | --- |
| `proId` | Thumbtack service identifier. |
| `name` / `businessName` | Display and business name. |
| `serviceCategory` | Category the pro was found under. |
| `serviceDescription` | Profile introduction, when published. |
| `rating` / `reviewCount` | Average star rating and number of reviews. |
| `reviewQualifier` | Thumbtack's qualitative rating label. |
| `hireCount` | Number of hires booked through Thumbtack. |
| `responseTime` / `responseTimeHours` | Display text and numeric average response time. |
| `topPro` / `topProYears` | Top Pro status and the years awarded. |
| `isBackgroundChecked` | Whether the public profile shows a passed background check. |
| `isVerified` | Whether the profile shows a business verification credential. |
| `yearsInBusiness` / `numEmployees` | Business age and employee count. |
| `instantBookable` / `availabilityText` | Instant-booking signal from the card. |
| `priceText` / `startingPrice` / `priceUnit` | Published price, when the pro shows one. |
| `urgencySignals` | Thumbtack demand/value signals. |
| `services` / `specialties` | Flat service list and grouped specialties. |
| `credentials` | Background check and business verification entries. |
| `businessHours` / `paymentMethods` / `socialLinks` | Profile details, when published. |
| `ratingHistogram` / `reviews` | Star distribution and up to five highlighted reviews. |
| `mediaImages` / `numPhotos` | Sample project photos and total count. |
| `reviewText` / `reviewerName` | Featured review excerpt and author. |
| `city` / `state` / `serviceArea` | Location context. |
| `profileUrl` / `avatarUrl` | Public profile and image links. |
| `businessFacts` | Raw trust and activity facts shown by Thumbtack. |
| `scrapedAt` | ISO timestamp. |

Fields a pro does not publish are omitted, never filled with placeholders.

### Input

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | Select | `search` | `search`, `byCategory`, `byProfile` or `byUrl`. |
| `category` | Select | `house-cleaning` | Service category for search and byCategory modes. |
| `state` | Select | `CA` | Two-letter state code for the primary location. |
| `city` | String | `san-francisco` | City slug or `City, ST`. |
| `locations` | Array | `[]` | Extra `City, ST` locations for pagination and market coverage. |
| `profileUrls` | Array | `[]` | Profile URLs for byProfile mode. |
| `startUrls` | Array | `[]` | Category URLs for byUrl mode. |
| `sortBy` | Select | `recommended` | `recommended`, `highest_rated`, `most_hires` or `fastest_response`. |
| `minRating` | Number | — | Minimum average rating. |
| `minReviews` | Integer | — | Minimum review count. |
| `minHires` | Integer | — | Minimum Thumbtack hire count. |
| `topProOnly` | Boolean | `false` | Keep Top Pro badge holders only. |
| `backgroundCheckedOnly` | Boolean | `false` | Keep background-checked pros only; profiles are opened for candidates. |
| `instantBookOnly` | Boolean | `false` | Keep instant-bookable pros only. |
| `includeProfileDetails` | Boolean | `false` | Open every matched profile for deep vetting fields. |
| `paginate` | Boolean | `true` | Continue through sort orders and nearby cities until `maxItems`. |
| `maxItems` | Integer | `5` | Hard cap on records. |

#### Example: top plumbers in New York with deep details

```json
{
  "mode": "search",
  "category": "plumber",
  "state": "NY",
  "city": "new-york",
  "sortBy": "most_hires",
  "minRating": 4.5,
  "minHires": 10,
  "includeProfileDetails": true,
  "maxItems": 20
}
```

#### Example: background-checked cleaners across three cities

```json
{
  "mode": "search",
  "category": "house-cleaning",
  "locations": ["Austin, TX", "Dallas, TX", "Houston, TX"],
  "backgroundCheckedOnly": true,
  "maxItems": 30
}
```

#### Example: nationwide roofers

```json
{
  "mode": "byCategory",
  "category": "roofing",
  "sortBy": "highest_rated",
  "maxItems": 50
}
```

### Pagination and location coverage

Thumbtack's public category page previews roughly 4-10 pros per city. With `paginate` enabled, the actor continues through the other three sort orders, then through nearby major cities, deduplicating on `proId`. Supply `locations` for deterministic coverage; use `byCategory` for a nationwide sweep.

### Notes and limits

- Every value comes from public Thumbtack pages, with no login, cookies or API key.
- Contact details (phone, email, street address) are not published on these pages and are not scraped.
- Deep fields such as background check and years in business require `includeProfileDetails` or a byProfile run and appear only when the pro publishes them.
- Reviews are capped at the five highlighted reviews Thumbtack shows publicly.
- A single city/category page is a preview, not the full directory; use locations, sort orders or byCategory to widen coverage.

### Data source

Thumbtack's public front-door category pages and public pro profile pages.

# Actor input Schema

## `mode` (type: `string`):

Choose how to find pros: a category + location search, a nationwide category sweep, direct profile URLs, or front-door category URLs.

## `category` (type: `string`):

Thumbtack service category used by search and byCategory modes.

## `state` (type: `string`):

Two-letter state code for the primary search location (mode=search).

## `city` (type: `string`):

City slug or `City, ST` for the primary search location, e.g. `san-francisco`, `new-york`, or `Austin, TX`.

## `locations` (type: `array`):

Optional list of extra `City, ST` locations. Each becomes its own search page and results are deduplicated, so this is how you paginate past a single city's preview.

## `profileUrls` (type: `array`):

Thumbtack pro profile URLs for mode=byProfile, e.g. `https://www.thumbtack.com/ca/san-francisco/house-cleaning/example/service/123456`.

## `startUrls` (type: `array`):

Thumbtack front-door category URLs for mode=byUrl, e.g. `https://www.thumbtack.com/tx/austin/plumbers`.

## `sortBy` (type: `string`):

Server-side order applied to each category page before filters run.

## `minRating` (type: `number`):

Keep only pros rated at or above this value (0-5).

## `minReviews` (type: `integer`):

Keep only pros with at least this many customer reviews.

## `minHires` (type: `integer`):

Keep only pros hired at least this many times through Thumbtack.

## `topProOnly` (type: `boolean`):

Keep only pros carrying the Top Pro badge.

## `backgroundCheckedOnly` (type: `boolean`):

Keep only pros whose public profile shows a passed background check. Profiles are fetched only for candidates that need checking.

## `instantBookOnly` (type: `boolean`):

Keep only pros whose card advertises instant booking.

## `includeProfileDetails` (type: `boolean`):

Open each matched pro's profile for background check, years in business, employees, services, credentials, hours, payment methods and reviews. Adds one browser request per record.

## `paginate` (type: `boolean`):

When a page returns fewer pros than requested, continue through the remaining sort orders and nearby major cities with deduplication.

## `maxItems` (type: `integer`):

Hard cap on emitted pro records.

## Actor input object example

```json
{
  "mode": "search",
  "category": "house-cleaning",
  "state": "CA",
  "city": "san-francisco",
  "locations": [],
  "profileUrls": [],
  "startUrls": [],
  "sortBy": "recommended",
  "topProOnly": false,
  "backgroundCheckedOnly": false,
  "instantBookOnly": false,
  "includeProfileDetails": false,
  "paginate": true,
  "maxItems": 2
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset containing all scraped Thumbtack pro profiles.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "category": "house-cleaning",
    "state": "CA",
    "city": "san-francisco",
    "locations": [],
    "profileUrls": [],
    "startUrls": [],
    "sortBy": "recommended",
    "topProOnly": false,
    "backgroundCheckedOnly": false,
    "instantBookOnly": false,
    "includeProfileDetails": false,
    "paginate": true,
    "maxItems": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/thumbtack-pro-vetting-and-hire-signal-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "category": "house-cleaning",
    "state": "CA",
    "city": "san-francisco",
    "locations": [],
    "profileUrls": [],
    "startUrls": [],
    "sortBy": "recommended",
    "topProOnly": False,
    "backgroundCheckedOnly": False,
    "instantBookOnly": False,
    "includeProfileDetails": False,
    "paginate": True,
    "maxItems": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/thumbtack-pro-vetting-and-hire-signal-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "category": "house-cleaning",
  "state": "CA",
  "city": "san-francisco",
  "locations": [],
  "profileUrls": [],
  "startUrls": [],
  "sortBy": "recommended",
  "topProOnly": false,
  "backgroundCheckedOnly": false,
  "instantBookOnly": false,
  "includeProfileDetails": false,
  "paginate": true,
  "maxItems": 2
}' |
apify call dataspryva/thumbtack-pro-vetting-and-hire-signal-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/thumbtack-pro-vetting-and-hire-signal-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/oPVwzqawh4uIalwM3/builds/H9uf3mT3x8nvTqzMi/openapi.json
