Overview
Getting Started
MARKETPLACE
Widgets
MCP Server
Find Pros
Categories
Keywords
Requests
Leads
Messages
On-Demand Orders
Reviews
User Accounts
Testing Your Marketplace Integration
PRO INTEGRATIONS
Leads
Messages
Reviews
Pro Profiles
Business Phone Numbers
Manage Webhooks
Testing Your Pro Integration
Support
Changelog
Terms and Policies
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.
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 lead: Open, Canceled, or Picked
- 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.
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","createdAt": "2024-06-13T17:18:01Z","status": "Open","customer": {"customerID": "519153480034934784","firstName": "Olivia","lastName": "Young","phone": "555-555-5555"},"business": {"businessID": "468046965846925323","name": "Robert's Remodeling","imageURL": "https://production-next-images-cdn.thumbtack.com/i/example.jpeg","phoneNumber": "+14155550100"},"request": {"requestID": "519153479873802240","customerID": "519153480034934784","contactedBusinesses": [{"businessID": "468046965846925323","name": "Robert's Remodeling","imageURL": "https://production-next-images-cdn.thumbtack.com/i/example.jpeg","negotiationID": "519153480500518912"}],"description": "Looking to fully renovate my kitchen.","category": {"categoryID": "201565295100608806","name": "Kitchen Remodel"},"location": {"city": "San Francisco","state": "CA","zipCode": "94117"},"details": [{"question": "Project scope","answer": "Full kitchen renovation"}],"attachments": []},"estimate": {"type": "OnSite"}}
Fetch all leads for a specific business:
GET /api/v4/businesses/{{businessID}}/negotiationsAuthorization: Bearer {{authCode}}
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.
The NegotiationCreatedV4 webhook includes the lead price at the time the lead is created. If the Pro is later refunded or credited for the lead, Thumbtack does not send a webhook event. To keep spend reporting accurate, periodically call GET /api/v4/negotiations/{negotiationID} for recent leads and check chargeState and refundDetails.
leadPrice always shows the original charge and is not reduced by a refund. When a refund or courtesy credit is granted, chargeState becomes Refunded and refundDetails shows the amounts. creditedAmount is a separate courtesy credit and is not part of refundedAmount, so don't add them together. These fields require the supply::negotiations.read scope.
Thumbtack sends NegotiationCreatedV4 once, when the lead is created. There is no webhook event for later status changes. To track a lead's status, call GET /api/v4/negotiations/{negotiationID} and check 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-statusAuthorization: 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
Reporting job status keeps more than your own system in sync. The signals you send flow back into Thumbtack's pro-facing experiences, so the pros you integrate with get proper credit for the work they win through your platform:
- Accurate status in the Thumbtack messenger — Signals such as job_complete and invoice_paid update the lead's labels in the Thumbtack messenger, keeping the conversation state consistent for both the pro and the customer.
- Hires counted in the pro's Performance Dashboard — job_complete and invoice_paid signals are recognized as hires and surface in the pro's Performance Dashboard. Updates are picked up automatically and refreshed multiple times a day, giving pros accurate performance analytics for jobs booked through your integration.
Last Updated: Oct 26th, 2026
On this page