> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehatchapp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Thumbtack v2
> What Hatch's Thumbtack v2 integration is, how it works, and where to begin.
### What does the Thumbtack v2 integration do?
Hatch offers a native integration with Thumbtack (v2) that you can activate within the App Marketplace (located in
your Hatch workspace). This integration syncs new Thumbtack leads to Hatch in real time so you can launch them into a
Speed to Lead campaign.
Thumbtack v2 uses Thumbtack's Partner API v4 webhook delivery: whenever a customer contacts your business through
Thumbtack, Thumbtack sends a `NegotiationCreatedV4` event to Hatch and Hatch creates a Contact and Opportunity record
for the lead.
A single Thumbtack v2 integration instance can manage **multiple** Thumbtack businesses. Each selected business gets
its own webhook subscription registered with Thumbtack and can be enabled or disabled individually.
Once a lead is synced with Hatch, the integration sends an automatic reply to the lead via the Thumbtack inbox so that
Thumbtack recognizes that you have replied. The default automatic reply is:
> *Thanks for contacting us! We will reach out to you directly.*
### How do you set up the integration?
#### **Requirements**
You will need the following to set up the integration:
* Hatch account with manager privileges
* Thumbtack Pro account with permissions to manage integrations on the businesses you want to connect
* Registered Hatch phone number in Thumbtack
#### **Setup Steps**
1. In Hatch, open the **App Marketplace**.
2. Under the **Lead Sources** filter, click the Connect button for **Thumbtack v2**.
3. Hatch uses OAuth 2.0 to connect with Thumbtack. Click **Connect** and log in to your Thumbtack account to authorize
the connection.
4. Select the Thumbtack businesses you want to integrate from the list. You can select more than one — each selected
business will get its own webhook subscription registered with Thumbtack. When successfully connected, the connection
bubble should turn blue when you return to the Hatch integration screen.
5. Enable the auto-reply (if desired), with the option to customize the message.
6. Click **Finish** to save and activate the integration.
7. After the integration has been activated, set up your audience and campaign workflow to launch your Thumbtack leads
into a Speed to Lead campaign.
#### Configuration Options
* **Business selection** — A single Thumbtack v2 integration instance can manage multiple Thumbtack businesses. Each
selected business gets its own webhook subscription with Thumbtack and can be individually enabled or disabled
without disconnecting the whole integration.
### When does Hatch sync data to/from Thumbtack?
#### Thumbtack → Hatch
Thumbtack data is synced to Hatch in real time via webhooks:
Thumbtack v2 leads are delivered via webhook the moment a customer contacts one of your connected Thumbtack
businesses. There is no polling interval.
* When a customer creates a new negotiation with one of your connected Thumbtack businesses
(`NegotiationCreatedV4`), Hatch receives a webhook and creates a Lead opportunity along with associated customer and
request data.
#### Hatch → Thumbtack
**Sync Communications**
When Hatch receives a Thumbtack lead, the integration sends an automatic reply back to the lead through Thumbtack so
your account is credited with a reply, as long as the auto reply is enabled in the instance.
The auto-reply message is configured in the Hatch integration instance. You can use the default message or customize your own!
* When a Hatch campaign is launched on a Thumbtack lead, an auto-reply is sent through the Thumbtack messenger so
that Thumbtack records that the lead was replied to.
### How is Thumbtack data stored in Hatch?
#### Opportunity Models
The Thumbtack v2 integration creates one type of Hatch opportunity:
* **Lead Opportunity** — Created from a Thumbtack `NegotiationCreatedV4` event. Includes customer, business,
request, and estimate data (see below).
#### Opportunity Creation & Update
When an **opportunity** is generated that doesn't match an existing **contact**, a new **contact** will be created. A
new **opportunity** will be added to an existing **contact** if a match is found.
The integration will create an additional (new) Hatch opportunity when:
* The synced Hatch External ID does not match any existing opportunity's Hatch External ID
### What Thumbtack data is available in Hatch?
#### Selecting Object Resources
Unlike some of our other integrations, the Thumbtack v2 integration does not expose individual resource toggles. Each
`NegotiationCreatedV4` webhook delivers the full set of fields documented below; whichever fields Thumbtack populates
for a given lead will be available on that opportunity. The only configuration that affects what data flows in is
which Thumbtack businesses you've enabled in the integration instance.
#### Available Resource Fields
The following fields are available in the **Lead opportunity** details:
| Resource | Field Name | Data Type |
| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
| Event | `event:eventType` | String (NegotiationCreatedV4) |
| Event | `event:description` | String |
| Event | `event:webhookID` | String |
| Event | `event:triggeredAt` | Date |
| Negotiation | `data:negotiationID` | String |
| Negotiation | `data:createdAt` | Date |
| Negotiation | `data:status` | String (Open, Canceled, Picked) |
| Negotiation | `data:leadPrice` | String (decimal) |
| Negotiation | `data:chargeState` | String (Created, Pending, Charged, Refunded) |
| Customer | `data:customer:customerID` | String |
| Customer | `data:customer:firstName` | String |
| Customer | `data:customer:lastName` | String |
| Customer | `data:customer:phone` | String |
| Business | `data:business:businessID` | String |
| Business | `data:business:name` | String |
| Business | `data:business:imageURL` | String (URI) |
| Business | `data:business:phoneNumber` | String |
| Business | `data:business:accessCode` | String |
| Request | `data:request:requestID` | String |
| Request | `data:request:customerID` | String |
| Request | `data:request:description` | String |
| Request | `data:request:travelPreferences:#` | String (CustomerTravelToProvider, ProviderTravelToCustomer, Remote) |
| Request Category | `data:request:category:categoryID` | String |
| Request Category | `data:request:category:name` | String |
| Contacted Businesses | `data:request:contactedBusinesses:#:businessID` | String |
| Contacted Businesses | `data:request:contactedBusinesses:#:name` | String |
| Contacted Businesses | `data:request:contactedBusinesses:#:imageURL` | String (URI) |
| Contacted Businesses | `data:request:contactedBusinesses:#:phoneNumber` | String |
| Proposed Times | `data:request:proposedTimes:#:start` | Date |
| Proposed Times | `data:request:proposedTimes:#:end` | Date |
| Booking | `data:request:booking:start` | Date |
| Booking | `data:request:booking:duration` | Number |
| Location | `data:request:location:address1` | String |
| Location | `data:request:location:address2` | String |
| Location | `data:request:location:city` | String |
| Location | `data:request:location:state` | String |
| Location | `data:request:location:zipCode` | String |
| Request Details | `data:request:details:#:question` | String |
| Request Details | `data:request:details:#:answer` | String |
| Attachments | `data:request:attachments:#:fileName` | String |
| Attachments | `data:request:attachments:#:fileSize` | Number |
| Attachments | `data:request:attachments:#:mimeType` | String |
| Attachments | `data:request:attachments:#:url` | String (URI) |
| Attachments | `data:request:attachments:#:description` | String |
| Estimate | `data:estimate:type` | String (Fixed, PerUnit, OnSite, Hourly, MoreInfo) |
| Estimate | `data:estimate:pricePerUnit` | String (decimal) |
| Estimate | `data:estimate:unitQuantity` | Number |
| Estimate | `data:estimate:unitName` | String |
| Estimate | `data:estimate:total` | String (decimal) |
#### Standard Field Mapping
Hatch standard fields are mapped from Thumbtack detail fields as detailed below.
**Lead Opportunity**
The base object of this opportunity model is the Thumbtack **Negotiation**. Therefore, (as an example) the **External
ID** field would indicate the ID of the Thumbtack **Negotiation** record.
In Lead opportunities, the following Hatch standard fields are mapped from Thumbtack detail fields:
| Hatch Standard Field | Thumbtack Detail Field |
| -------------------------------------------------------------- | -------------------------- |
| **External ID** | `data:negotiationID` |
| **External Contact ID** | `data:customer:customerID` |
| **External Created At** | `data:createdAt` |
| **External Updated At** *(used for Hatch opportunity sorting)* | `data:createdAt` |
| **First Name** | `data:customer:firstName` |
| **Last Name** | `data:customer:lastName` |
| **Phone** | `data:customer:phone` |
### FAQ
A single Thumbtack v2 integration instance supports connecting multiple Thumbtack businesses. During setup, select
all of the businesses you want to route into Hatch — each one will be registered with its own webhook subscription on
the Thumbtack side. You can also enable or disable individual businesses later without disconnecting the whole
integration.
The Thumbtack v4 Partner API does not return a customer email address for leads, so Hatch only stores a phone
number for Thumbtack v2 contacts. If your campaigns rely on email outreach, plan around the phone-only contact
channel.
We will be offering migrations to Thumbtack v2 at a later date. Once available, we will provide more information!