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.

Update job status

Notify Thumbtack when a lead moves through the job lifecycle on your platform (e.g., scheduled, completed, canceled). This keeps Thumbtack's view of the job in sync with yours and triggers downstream product flows. For full endpoint details, see the API Reference.

POST /api/v4/negotiations/{{negotiationID}}/job-status
Authorization: Bearer {{authCode}}

Request body:

{
    "status": "job_complete",
    "partnerStatusChangedAt": "2024-06-14T09:30:00Z",
    "invoiceAmountInCents": 125000
}

Fields:

Field	Required	Description
status	Yes	The job's current signal status. See values below.
partnerStatusChangedAt	Yes	Timestamp of when the status transition actually occurred on your platform — not when this API call is made.
invoiceAmountInCents	No	Amount invoiced for the job, in cents. Applicable when status is job_complete or invoice_paid.

Status values:

Value	Meaning
not_scheduled	Default state — no appointment yet.
appt_scheduled	A job or onsite estimate has been scheduled.
job_complete	The job has been completed.
invoice_paid	The job is complete and the customer has paid the invoice.
customer_cancel	The customer canceled the job.
pro_cancel	The pro canceled the job.

Response: 200 OK on success. Errors follow the standard problem response format.

When to call this endpoint: Send an update each time a lead's status changes on your platform so Thumbtack's lifecycle and customer-facing messaging stay accurate. Use partnerStatusChangedAt to reflect the true time of the change, even if the API call is delayed or retried.

Required scope: supply::negotiations.write

Last Updated: May 1st, 2026

On this page

Leads

Leads

What is a lead?

Get a lead by ID

Get leads for a business

Receive leads in real-time

Update job status

Related