Leads

Receive and manage leads from Thumbtack. View job details, customer information, messages, and status updates.

API mapping: In the Thumbtack API, leads are called negotiations, and all endpoints use /api/v4/negotiations/. On this page, the terms are interchangeable.

What is a lead?

When a homeowner on Thumbtack contacts a pro about a service, Thumbtack creates a lead. A lead contains:

Job details — service type, project description, location, scheduling preferences
Customer info — name, contact details (based on scopes)
Status — current state of the job (new, in progress, completed, etc.)
Messages — conversation history between the customer and pro
Invoices and scheduling — included once a pro has sent a quote or scheduled the job

As a supply partner, you'll typically receive leads in real-time via webhooks, then use the API to fetch full details and manage the lead lifecycle.

Ready to start receiving leads? See the Implementation Guide for step-by-step setup.

Get a lead by ID

Fetch full details for a specific lead. For full endpoint details, see the Negotiations API Reference.

GET /api/v4/negotiations/{{negotiationID}}
Authorization: Bearer {{authCode}}

Response:

{
  "negotiationID": "519153480500518912",
  "status": "active",
  "category": {
    "categoryID": "201565295100608806",
    "name": "Kitchen Remodel"
  },
  "customer": {
    "customerID": "519153480034934784",
    "displayName": "Olivia Y.",
    "location": {
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94117"
    }
  },
  "business": {
    "businessID": "468046965846925323",
    "name": "Robert's Remodeling"
  },
  "details": [
    {
      "question": "Project scope",
      "answer": "Full kitchen renovation"
    }
  ],
  "createTime": "2024-06-13T17:18:01Z"
}

Get leads for a business

Fetch all leads for a specific business:

GET /api/v4/businesses/{{businessID}}/negotiations
Authorization: Bearer {{authCode}}

Receive leads in real-time

Most partners receive leads via webhooks rather than polling. When a new lead is created on Thumbtack, we send a NegotiationCreatedV4 event to your registered webhook URL with the full lead payload.

→ See the Implementation Guide for step-by-step setup.

Last Updated: May 1st, 2026

On this page

Leads