Partner Platform

Request Access

Overview

Getting Started

Widgets

Categories

Keywords

Reviews

Users

Businesses

Businesses Search

Negotiations

Messages

Requests

Help

Changelog

Terms and Policies

Businesses Search (fka Pros)

Discover how to display Businesses from Thumbtack on your platform.

Overview

The Businesses Search API allows you to search for and return a list of Businesses to your users, who can then review and hire any returned Business.

Pre-read: Search Context

In fetching Businesses from Thumbtack, we introduce the concept of a Search. A Search is a short-lived context that contains necessary details regarding your search for Businesses. For example, a Search would contain the zipCode you are searching for Businesses within, the categoryID you wish to show Businesses for, and requestFormDetails which contains questions (and their associated answers) to help narrow down which Businesses are compatible.

Get Businesses

Utilizing our Businesses Search API, you can create a Search Context which, by extension, returns a list of matching Businesses and several data points for each Businesses.

Worked Example

Consider the following ask: "Show me a Handyman in the Beverly Hills Area (zipCode 90210)."
We would begin by creating a new Businesses Search:
POST /api/v4/businesses/search HTTP/2
authorization: Bearer {{clientCredentials}}
content-type: application/json
{
    "searchQuery": "handyman",
    "zipCode": "90210",
    "utmData": {
        "utm_source": "{{your utm_source}}"
    },
    "limit": 1
}
Which would return JSON of the form:
{
  "searchID": "545691258236567552",
  "data": [
    {
      "businessID": "479288677004124167",
      "businessName": "Max",
      "businessIntroduction": "Hello!  I am a professional handyman in Los Angeles.\n My approach to each client is individual, so I am always ready to listen to your needs and wishes. I work quickly and efficiently, but always with attention to detail.\n  I respond quickly to requests.\n  You can be sure that you will receive the best service!",
      "quote": {
        "startingCost": 6000,
        "costUnit": "hour"
      },
      "businessLocation": "Glendale, CA",
      "numberOfEmployees": 1,
      "numberOfSimilarJobsDone": 0,
      "isTopPro": false,
      "rating": 5,
      "numberOfReviews": 170,
      "featuredReview": "Max is an exceptional handyman! Punctual, quick, and easy to work with. His work is quality, and he doesn’t rush which I appreciate. Highly recommend Max for any home improvement projects.",
      "yearsInBusiness": 4,
      "numberOfHires": 304,
      "responseTimeHours": 0,
      "servicePageURL": "https://thumbtack.com/ca/glendale/handyman/max/service/479288677004124167?category_pk=109125193401647362&project_pk={{projectPK}}&search_query=handyman&utm_medium=partnership&utm_source={{your utm_source}}&utm_tt_session={{utmTTSession}}&zip_code=90210",
      "businessImageURL": "https://production-next-images-cdn.thumbtack.com/i/479289161404375045/desktop/standard/profile-legacy",
      "pills": [
        "low_price"
      ],
      "isBusinessLicenseVerified": false,
      "isBackgroundChecked": true,
      "widgets": {
        "requestFlowURL": "https://thumbtack.com/embed/request-flow?category_pk=109125193401647362&page_source=<pageSource>&project_pk={{projectPK}}&search_query=handyman&service_pk=479288677004124167&utm_medium=partnership&utm_source={{your utm_source}}&utm_tt_session={{utmTTSession}}&zip_code=90210",
        "servicePageURL": "https://thumbtack.com/ca/glendale/handyman/max/service/479288677004124167?category_pk=109125193401647362&project_pk=545691258236567552&search_query=handyman&utm_medium=partnership&utm_source=<your utm_source>&utm_tt_session=<utmTTSession>&zip_code=90210"
      }
    }
  ],
  "metadata": {
    "categoryID": "109125193401647362",
    "categoryName": "Handyman",
    "categoryImageURL": "https://production-next-images-cdn.thumbtack.com/i/323489611327971335/small/standard/hero",
    "zipCode": "90210",
    "requestLocation": "Beverly Hills, CA",
    "seeMoreProsURL": "https://thumbtack.com/instant-results/?category_pk=109125193401647362&project_pk={{projectPK}}&utm_medium=partnership&utm_source={{your utm_source}}&utm_tt_session={{utmTTSession}}&zipCode=90210&zip_code=90210"
  }
}
With the returned data, there are a few important call-outs:
  • result["searchID"]: The generated Search ID for this Businesses Search.
  • result["data"][0]["servicePageURL"]: The URL to Thumbtack's site to view the Business' Service Page.
  • result["data"][0]["widgets"]["requestFlowURL"]: The URL to include within an iframe to embed going through the Request Flow to book this Business on your Platform. See more at the Request Flow Widget Docs.
  • result["data"][0]["widgets"]["servicePageURL"]: The URL to include within an iframe to embed the Business' Service Page Flow on your Platform. See more at the Service Page Widget Docs.
  • result["metadata"]["seeMoreProsURL"]: A URL to Thumbtack's site to show additional Business beyond what was returned in this API call.
With the returned result["searchID"], you can then issue a request to fetch the results anew via:
GET /api/v4/businesses/search/{{searchID}}?utmData[utm_source]={{utm_source}} HTTP/2
authorization: Bearer {{clientCredentials}}
content-type: application/json
Or, alternatively, you can update your Businesses Search to return adjusted results. For example, you can fetch results within San Francisco (zipCode 94016) by issuing the following call:
PATCH /api/v4/businesses/search/{{searchID}}?limit=1 HTTP/2
authorization: Bearer {{clientCredentials}}
content-type: application/json
{
    "utmData": {
        "utm_source": "{{your utm_source}}"
    },
    "zipCode": "94016"
}

Get Filtered Businesses

In certain scenarios, you may wish to provide your users the ability to provide free-formed text containing a description of the service they are after. For example, a user could input a query such as I need a house cleaner every 2 weeks for my house that has 4 bedrooms and 4 bathrooms.
Rather than utilizing the /api/v4/businesses/search Route, you can utilize the /api/v4/businesses/search-filtered Route.
Continuing with the above query, you would submit the following request which would return data formatted exactly the same as from /api/v4/businesses/search-filtered:
POST /api/v4/businessess/search-filtered HTTP/2
authorization: Bearer {{clientCredentials}}
content-type: application/json
{
    "userQuery": "I need a house cleaner every 2 weeks for my house that has 4 bedrooms and 4 bathrooms",
    "zipCode": "90210",
    "utmData": {
        "utm_source": "{{your utm_source}}"
    },
    "limit": 1
}
If you have additional metadata on this user's request (that is not user-provided), you can provide it via the projectMetadata key in the payload.
Additionally, you can specify a categoryID if you already know which category of Businesses should be returned for this user's query.
As a peek behind the scenes - we use an LLM to extract data from the provided userQuery (and projectMetadata, if provided) to filter the Businesses returned to guarantee that they can do the job given all the provided data.

On this page