NAV Navbar
Thumbtack API
shell

Introduction

The purpose of this API is to enable Supply Partners to integrate Thumbtack leads into their customer acquisition workflows. This is accomplished by supporting two functions - (1) lead transfer and (2) two way messaging. To support lead transfer, the Supply Partner will expose an API endpoint that Thumbtack will call. To support two way messaging, both Thumbtack and the Supply Partner will expose API endpoints for the other party to call.

Your use of our API is subject to Thumbtack's API Terms of Use.

Authentication

STEP 1: Get Client Credentials

Contact Thumbtack Partnership team for get the client-side credentials. These credentials will contain these two piece of information:

While requesting the client credentials, partners will have to provide redirectURL to the Thumbtack team.

Test OAuth flow during API Integration

Partners can test the OAuth flow by requesting the test client. They will need two separate clients for testing and production. They will have to contact the Thumbtack partnership team for creating the test client which will allow you to test the entire OAuth flow. They will have to provide different redirectURL for the Production credentials and staging credentials.

STEP 2: Connect Thumbtack account with Partner

Sample URL

https://thumbtack.com/services/partner-connect/?client_id=THUMBTACK%20INTERNAL&redirect_uri=http://redirect.thumbtack.com&response_type=code&scope=messages

Use the consumer key as a client_ID that Thumbtack provided to you to request an AuthCode. Also, include the redirect_url so that Thumbtack knows where to redirect users after they authorize access to their data.

https://thumbtack.com/services/partner-connect/?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URL>&response_type=code&scope=<SCOPE>

Expected Parameters in the URL

Parameter Type Description Required
client_id string Consumer key provided by Thumbtack Y
scope string Authorization scopes allow to access specific information from Thumbtack. Pass “messages” here Y
redirect_uri string Thumbtack redirects Pro to this URL after they authorization N
response_type string Must contain string code as a response type Y
state string Client can insert state information that will be appended to the redirect_uri upon success user authorization N

Test OAuth flow during API Integration

Sample URL

https://thumbtack.com/services/partner-connect/?client_id=%3CCLIENT_ID%3E&redirect_uri=%3CREDIRECT_URL%3E&response_type=code&scope=messages

Partners will be able to get the AuthCode with the test Client via partner connect URL.

STEP 3: Pro Authorizes Partner

Pro can select the Thumbtack Business name from the dropdown and click on the “Confirm Connection” button to Authorize that partner.

image info

Test OAuth flow during API Integration

NOTE: If Partners are using test Client, they can generate the Auth-code as many times as they want. They are not required to disconnect the flow before issuing the Auth-Code again.

STEP 4: Authorization Code

Sample URL when Redirect URL is https://redirect.thumbtack.com

https://redirect.thumbtack.com/?code=BnCICCQ9KWF6WXj_xtiN3A

After confirming the connection, There are two ways the client will receive auth-code:

<REDIRECT_URL>/?code=<AUTHORIZATION_CODE>&scope=messages

image info

Expected Parameters in the URL

Parameter Type Description
code string Authorization code appended to redirect_url in the previous step

Grab the Authorization Code and follow the below steps to get the Access Token.

Auth code expiry time - 5 minutes

Test OAuth flow during API Integration

Sample URL when Redirect URL is https://redirect.thumbtack.com

https://redirect.thumbtack.com/?code=BnCICCQ9KWF6WXj_xtiN3A

This step issues the auth-code for test client same as the production flow. Please check the above information for more details.

NOTE: If Partners are using test Client, they can generate the Auth-code as many times as they want. They are not required to disconnect the flow before issuing the Auth-Code again.

STEP 5: Request Access Token

Sample Authorization Header

Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK=

Sample Request

curl --location --request POST 'https://pro-api.thumbtack.com/v2/tokens/access?grant_type=authorization_code&code=BnCICCQ9KWF6WXj_xtiN3A&redirect_uri=http://redirect.thumbtack.com&token_type=AUTH_CODE' \
--header 'Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK='

Sample Response

{
   "access_token": "1.eyJCdXNpbmVzc1BLIjozODgwMDYwNjczNTExNTA1OTUsIkNsaWVudElEIjoiVEhVTUJUQUNLIElOVEVSTkFMIiwiU2NvcGUiOlsibWVzc2FnZXMiXSwiRXhwaXJlc0F0IjoiMjAyMS0xMC0xNFQwMjo1OToyOS44MjIwMDU2ODhaIiwiU3JjQXV0aENvZGUiOiIwNjcwODgwODI0M2QyOTYxN2E1OTc4ZmZjNmQ4OGRkY2UzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUifQ.qJDfeuYfdFZCSVQmBUgr_kDoZeeEUD4y4oVTVMEc4EQ",
   "token_type": "bearer",
   "expires_in": 3600,
   "refresh_token": "_s3cnwGAb5VgBt-CmYFSOw"
}

Once the pro authorizes access, the user is redirected back to the URL with the authorization code. This API will use an authorization code from the request return access token and refresh token in the response.

Request Endpoint

POST https://pro-api.thumbtack.com/v2/tokens/access

Request Header

Authorization: Basic <B64-encoded_oauth_credentials>

The Authorization: Basic authorization header is generated through a Base64 encoding of <client_id>:<client_secret>. You can use https://www.base64encode.org/ to see how headers should be encoded.

Expected Request Params

Parameter Type Description Required
grant_type string Must contain string authorization_code as a grant type Y
code string Authorization code appended to redirect_url in the step-3 Y
redirect_uri string Thumbtack redirected to this URL after they authorization Y
token_type string Must contain string AUTH_CODE as a token type Y

Expected Response Params

Parameter Type Description Required
access_token string The access token issued by the authorization server Y
token_type string Type of the token issued. Must return bearer as a token type Y
expires_in number Access Token lifetime in seconds. The default expiry is 3600 seconds (1 hour). Y
refresh_token string The refresh token issued by the authorization server Y

Access Token expiry time - 1 hour

Refresh Token expiry time - 720 hours

Test OAuth flow during API Integration

Sample Request

curl --location --request POST 'https://pro-api.thumbtack.com/v2/tokens/access?grant_type=authorization_code&code=BnCICCQ9KWF6WXj_xtiN3A&redirect_uri=http://redirect.thumbtack.com&token_type=AUTH_CODE' \
--header 'Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK='

Sample Response

{
   "access_token": "1.eyJCdXNpbmVzc1BLIjozODgwMDYwNjczNTExNTA1OTUsIkNsaWVudElEIjoiVEhVTUJUQUNLIElOVEVSTkFMIiwiU2NvcGUiOlsibWVzc2FnZXMiXSwiRXhwaXJlc0F0IjoiMjAyMS0xMC0xNFQwMjo1OToyOS44MjIwMDU2ODhaIiwiU3JjQXV0aENvZGUiOiIwNjcwODgwODI0M2QyOTYxN2E1OTc4ZmZjNmQ4OGRkY2UzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUifQ.qJDfeuYfdFZCSVQmBUgr_kDoZeeEUD4y4oVTVMEc4EQ",
   "token_type": "bearer",
   "expires_in": 3600,
   "refresh_token": "_s3cnwGAb5VgBt-CmYFSOw"
}

Partners will be able to use the test auth-code and call /tokens API to get the test access token and refresh token pair in the /token API response. Test token's behavior is the same as the production environment.

STEP 6: Refresh Access Token

Sample Authorization Header

Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK=

Sample Request 

curl --location --request POST 'https://pro-api.thumbtack.com/v2/tokens/access?grant_type=refresh_token&refresh_token=zRw4chXenfjNLenO2_lVOQ&token_type=REFRESH' \
--header 'Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK='

Sample Response

{
   "access_token": "1.eyJCdXNpbmVzc1BLIjozMTQxNDgwOTYyOTIxODQyNDMsIkNsaWVudElEIjoiVEhVTUJUQUNLIElOVEVSTkFMIiwiU2NvcGUiOltdLCJFeHBpcmVzQXQiOiIyMDIxLTEwLTE0VDAyOjQ1OjA2LjI4NjUwNzkxOFoiLCJTcmNBdXRoQ29kZSI6ImIzYzUzNjk3ZGU0ZTlmNWQxNTk2NDhmMGM2MTc3YWRhZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NSJ9.tgDkhV1ooM1C7UjWhZ_mCXbzF11YH4NgsweJdfvG-f8",
   "token_type": "bearer",
   "expires_in": 3600,
   "refresh_token": "eoZNGASGdTWop1jINi-ouQ"
}

When Access Token expires, use the below API with refresh token which has a long lifetime, to get a new access token and refresh token pair.

Request Endpoint

POST https://pro-api.thumbtack.com/v2/tokens/access

Request Header

Authorization: Basic <B64-encoded_oauth_credentials>

The Authorization: Basic authorization header is generated through a Base64 encoding of <client_id>:<client_secret>. You can use https://www.base64encode.org/ to see how headers should be encoded.

Expected Request Params

Parameter Type Description Required
grant_type string Must contain string refresh_token as a grant type Y
refresh_token string Refresh Token value that you received along with the access token in step:4 Y
token_type string Must contain string REFRESH as a token type Y

Expected Response Params

Parameter Type Description Required
access_token string The access token issued by the authorization server Y
token_type string Type of the token issued. Must return bearer as a token type Y
expires_in number Access Token lifetime in seconds. The default expiry is 3600 seconds (1 hour). Y
refresh_token string The refresh token issued by the authorization server Y

Error handling with grace period

We have implemented a grace period logic in OAuth refresh token flow to handle Network errors, Time-out errors or similar one. If you receive null in the response to /tokens/access API at the time of refreshing the token, we encourage Partners to implement the retry logic on their side which will call /tokens/access API with same refresh token to get the valid response. Grace period time - 10 sec

Test OAuth flow during API Integration

Sample Request

curl --location --request POST 'https://pro-api.thumbtack.com/v2/tokens/access?grant_type=refresh_token&refresh_token=zRw4chXenfjNLenO2_lVOQ&token_type=REFRESH' \
--header 'Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK='

Sample Response

{
   "access_token": "1.eyJCdXNpbmVzc1BLIjozODgwMDYwNjczNTExNTA1OTUsIkNsaWVudElEIjoiVEhVTUJUQUNLIElOVEVSTkFMIiwiU2NvcGUiOlsibWVzc2FnZXMiXSwiRXhwaXJlc0F0IjoiMjAyMS0xMC0xNFQwMjo1OToyOS44MjIwMDU2ODhaIiwiU3JjQXV0aENvZGUiOiIwNjcwODgwODI0M2QyOTYxN2E1OTc4ZmZjNmQ4OGRkY2UzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUifQ.qJDfeuYfdFZCSVQmBUgr_kDoZeeEUD4y4oVTVMEc4EQ",
   "token_type": "bearer",
   "expires_in": 3600,
   "refresh_token": "_s3cnwGAb5VgBt-CmYFSOw"
}

Partners will be able to use the test auth-code and call /tokens API to get the test access token and refresh token pair in the /token API response. Test token's behavior is the same as the production environment.

Thumbtack Endpoints

Thumbtack will expose the following endpoints to Partners. All endpoints should be versioned to support future schema changes. Endpoints will use HTTP basic authentication, and Thumbtack will provide Partners with a username and password for Partners to call these endpoints. Note that passing in the Content-Type header is required.

Messages

Sample Authorization Header

Authorization: Bearer 1.eyJCdXNpbmVzc1BLIjozOTUwMjMyMDc2MTEwMjMzNzIsIkNsaWVudElEIjoicHJvbmV4aSIsIlNjb3BlIjpbIm1lc3NhZ2VzIl0sIkV4cGlyZXNBdCI6IjIwMjEtMTAtMjJUMjI6MTM6MDMuNDMwMTMwNzQ4WiIsIlNyY0F1dGhDb2RlIjoiNGJlOTFjNTIyN2RmOGIxNTdjNjZlMTlkOGRhMjI0ZTRlM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1IiwiQWNjb3VudElEIjozMDczMDYyNDIwMTgzOTQzMTZ9.CyNhsuC0JQDM9zNrpjduD7Ja_qLbQw51bq_H7Ry39C4

Sample Request

curl --location --request POST 'https://api.thumbtack.com/v2/business/395023207611023372/lead/123/message' \
--header 'Authorization: Bearer 1.eyJCdXNpbmVzc1BLIjozOTUwMjMyMDc2MTEwMjMzNzIsIkNsaWVudElEIjoicHJvbmV4aSIsIlNjb3BlIjpbIm1lc3NhZ2VzIl0sIkV4cGlyZXNBdCI6IjIwMjEtMTAtMjJUMjI6MTM6MDMuNDMwMTMwNzQ4WiIsIlNyY0F1dGhDb2RlIjoiNGJlOTFjNTIyN2RmOGIxNTdjNjZlMTlkOGRhMjI0ZTRlM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1IiwiQWNjb3VudElEIjozMDczMDYyNDIwMTgzOTQzMTZ9.CyNhsuC0JQDM9zNrpjduD7Ja_qLbQw51bq_H7Ry39C4' \
--header 'Content-Type: application/json' \
--data-raw '{"text": "Hello, how can I help you?"}'

Sample Response

{
    "status": "success"
}

Send messages on behalf of the Pro to a Thumbtack customer for a given lead. This is an endpoint Thumbtack has created for Partners to call. Thumbtack provides both a production and test environment endpoint.

Request Endpoint (Production Environment)

POST https://pro-api.thumbtack.com/v2/business/{BusinessID}/lead/{leadID}/message

:businessID is the identifier of your business. :leadID is the identifier of the lead whose customer you wish to message.

HTTP Endpoint (Test Environment)

POST https://staging-pro-api.thumbtack.com/v2/business/{BusinessID}/lead/{leadID}/message

:businessID is the identifier of your business. :leadID is the identifier of the lead whose customer you wish to message.

Request Header

Authorization: Bearer <access_token>

access_token is the value that you received along with the /token/access API.

Expected Request Body

Parameter Type Description Required
text string Text of the message Y

Test OAuth flow during API Integration

Sample Request

curl --location --request POST 'https://api.thumbtack.com/v2/business/395023207611023372/lead/123/message' \
--header 'Authorization: Bearer 1.eyJCdXNpbmVzc1BLIjozOTUwMjMyMDc2MTEwMjMzNzIsIkNsaWVudElEIjoicHJvbmV4aSIsIlNjb3BlIjpbIm1lc3NhZ2VzIl0sIkV4cGlyZXNBdCI6IjIwMjEtMTAtMjJUMjI6MTM6MDMuNDMwMTMwNzQ4WiIsIlNyY0F1dGhDb2RlIjoiNGJlOTFjNTIyN2RmOGIxNTdjNjZlMTlkOGRhMjI0ZTRlM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1IiwiQWNjb3VudElEIjozMDczMDYyNDIwMTgzOTQzMTZ9.CyNhsuC0JQDM9zNrpjduD7Ja_qLbQw51bq_H7Ry39C4' \
--header 'Content-Type: application/json' \
--data-raw '{"text": "Hello, how can I help you?"}'

Sample Response

{
    "status": "success"
}

If the access token passes as an authorization header related to the test client, Thumbtack will only validate the token and return the dummy response. (As test clients are only for testing the OAuth flow and to check if they can hit the actual API with that token or not.)

Thumbtack Info

Sample Authorization Header

Authorization: Bearer 1.eyJCdXNpbmVzc1BLIjozOTUwMjMyMDc2MTEwMjMzNzIsIkNsaWVudElEIjoicHJvbmV4aSIsIlNjb3BlIjpbIm1lc3NhZ2VzIl0sIkV4cGlyZXNBdCI6IjIwMjEtMTAtMjJUMjI6MTM6MDMuNDMwMTMwNzQ4WiIsIlNyY0F1dGhDb2RlIjoiNGJlOTFjNTIyN2RmOGIxNTdjNjZlMTlkOGRhMjI0ZTRlM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1IiwiQWNjb3VudElEIjozMDczMDYyNDIwMTgzOTQzMTZ9.CyNhsuC0JQDM9zNrpjduD7Ja_qLbQw51bq_H7Ry39C4

Sample Request

curl --location --request GET 'https://pro-api.thumbtack.com/v2/get-thumbtack-info' \
--header 'Authorization: Bearer 1.eyJCdXNpbmVzc1BLIjozMTQxNDgwOTYyOTIxODQyNDMsIkNsaWVudElEIjoiODJNUlY1MmFGSXUwU0ZZTEpPM3NzcHg3aGF3RjVaZXozdVJTVkNRMCtsST0iLCJTY29wZSI6WyJtZXNzYWdlcyJdLCJFeHBpcmVzQXQiOiIyMDIxLTExLTEyVDIyOjE0OjU3Ljc3MzI5NTgyM1oiLCJTcmNBdXRoQ29kZSI6IjE2NDE1OWY1MDk2YzgxZTRiNzA5ODY4MjJjYWI3MWQzZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NSIsIkFjY291bnRJRCI6MzgxMzU1NTEwMjM1Mjc1Mjc0fQ.IXT9OXvHO43u7Z4SZPjNtbQ_hipMIAbNI7GmpmvobUE' \
--header 'Content-Type: application/json'

Sample Response

{
  "business_pk": "388006067351150595",
  "client_id": "THUMBTACK INTERNAL",
  "scope": [
    "messages"
  ],
  "business_name": "cleaner business"
}

Return thumbtack information by parsing the access_token value that you received along with the /token API.

HTTP Endpoint

GET https://pro-api.thumbtack.com/v2/get-thumbtack-info

Request Header

Authorization: Bearer <access_token>

access_token is the value that you received along with the /token/access API.

Expected Response Params

Parameter Type Description Required
business_pk string Business PK related to the access token. Y
client_id string Consumer key provided by Thumbtack which related to the access token. Y
scope array Authorization scopes allow to access specific information from Thumbtack. Y
business_name string Business Name related to the access token. Y

Test OAuth flow during API Integration

Sample Request

curl --location --request GET 'https://pro-api.thumbtack.com/v2/get-thumbtack-info' \
--header 'Authorization: Bearer 1.eyJCdXNpbmVzc1BLIjozMTQxNDgwOTYyOTIxODQyNDMsIkNsaWVudElEIjoiODJNUlY1MmFGSXUwU0ZZTEpPM3NzcHg3aGF3RjVaZXozdVJTVkNRMCtsST0iLCJTY29wZSI6WyJtZXNzYWdlcyJdLCJFeHBpcmVzQXQiOiIyMDIxLTExLTEyVDIyOjE0OjU3Ljc3MzI5NTgyM1oiLCJTcmNBdXRoQ29kZSI6IjE2NDE1OWY1MDk2YzgxZTRiNzA5ODY4MjJjYWI3MWQzZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NSIsIkFjY291bnRJRCI6MzgxMzU1NTEwMjM1Mjc1Mjc0fQ.IXT9OXvHO43u7Z4SZPjNtbQ_hipMIAbNI7GmpmvobUE' \
--header 'Content-Type: application/json'

Sample Response

{
  "business_pk": "388006067351150595",
  "client_id": "THUMBTACK INTERNAL",
  "scope": [
    "messages"
  ],
  "business_name": "cleaner business"
}

Partners will be able to use the access token to get the thumbtack information like (BusinessPK, clientID, etc.)

Disconnect from OAuth Flow

Sample Authorization Header

Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK=

Sample Request

curl --location --request POST 'https://pro-api.thumbtack.com/v2/disconnect-partner?business_pk=432428213655306241' \
--header 'Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK='

Sample Response

{
  "business_pk": "432428213655306241",
  "client_id": "THUMBTACK INTERNAL"
}

Removes tokens and disables the service on the Thumbtack side so which will allow the partner/pro to trigger the OAuth initialization flow again.

HTTP Endpoint

POST https://pro-api.thumbtack.com/v2/disconnect-partner

Request Header

Authorization: Basic <B64-encoded_oauth_credentials>

The Authorization: Basic authorization header is generated through a Base64 encoding of <client_id>:<client_secret>. You can use https://www.base64encode.org/ to see how headers should be encoded.

Expected Request Params

Parameter Type Description Required
business_pk string business_pk that you can get via /get-thumbtack-info API Y

Expected Response Params

Parameter Type Description Required
business_pk string Business PK Y
client_id string Consumer key provided by Thumbtack related to the business. Y

Test OAuth flow during API Integration

Sample Request

curl --location --request POST 'https://pro-api.thumbtack.com/v2/disconnect-partner?business_pk=432428213655306241' \
--header 'Authorization: Basic VEhVTUJUQUNLIElOVEVSTkFMOlp4UnFMbnZZQUMzSERqVFlkem9sdFEK='

Sample Response

{
  "business_pk": "432428213655306241",
  "client_id": "THUMBTACK INTERNAL"
}

Disconnect flow will remove all the previous auth-codes and tokens from the Thumbtack database.

NOTE: Thumbtack team will always recommend that partners should call this endpoint when they completed the testing so that Thumbtack can do a cleanup in order to remove older tokens and older auth codes.

Partner Endpoints

Partners will expose the following endpoints to Thumbtack. All endpoints should be versioned to support future schema changes. Endpoints will use HTTP basic authentication, and Partners will provide Thumbtack with username and password for Thumbtack to call these endpoints.

Leads

Sample Request Body

{
  "leadID": "299614694480093245",
  "createTimestamp": "1498760294",
  "request": {
    "requestID": "2999842694480093245",
    "category": "Interior Painting",
    "title": "Interior Painting",
    "description": "There is a stain on the door that needs to be touched up.",
    "schedule": "Date: Tue, May 05 2020\nTime: 6:00 PM\nLength: 3.5 hours",
    "location": {
      "city": "San Jose",
      "state": "CA",
      "zipCode": "95125"
    },
    "travelPreferences": "Professional must travel to my address.",
    "details": [
      {
        "question": "Type of property",
        "answer": "Home"
      },
      {
        "question": "Number of rooms",
        "answer": "4 rooms"
      }
    ]
  },
  "customer": {
    "customerID": "331138063184986319",
    "name": "John Davis",
    "phone": "1234567890"
  },
  "business": {
    "businessID": "286845156044809661",
    "name": "Tim's Painting Business"
  },
  "leadType": "ESTIMATION",
  "leadPrice": null,
  "chargeState": null
}

Sample Request (assuming above JSON was saved as data.json)

curl -X POST https://www.api.[partner].com/v1/lead
    -d data.json
    -H 'Content-Type:application/json'
    --user '<thumbtack_username>:<thumbtack_password>'

This endpoint will be called by Thumbtack to send leads to Partners. Leads will be coming from the Thumbtack customer to the Partner's Pro (represented as a business on Thumbtack).

HTTP Endpoint

POST https://api.[partner].com/v1/lead

Note that the naming of this endpoint is flexible and dictated by the Partner.

Expected Request Body

Parameter Type Description Required
leadID string ID of the lead Y
createTimestamp string Unix timestamp (seconds) of when lead was created in UTC timezone Y
request object JSON request object Y
request.requestID string ID of the request Y
request.category string Category of the request Y
request.title string Title of the request Y
request.description string Description of the request N
request.schedule* string Details on when the customer wants to complete the job N
request.location object JSON location object Y
request.location.city string City for the request location Y
request.location.state string State (two letter abbreviation) for the request location Y
request.location.zipCode string Zip code (five digit) for the request location Y
request.travelPreferences string Travel preferences of the customer Y
request.details array Array of details about the request N
request.details.[i].question string Request specific question about the job (see example below for clarification) Y
request.details.[i].answer string Answer to the question (see example below for clarification) Y
customer object JSON customer object Y
customer.customerID string ID of the customer Y
customer.name string Name of the customer Y
customer.phone** string Phone number of the customer if we have it N
business object JSON business object Y
business.businessID string ID of the business (pro) Y
business.name string Business name Y
price string Price estimate for the job N
leadType string Type of lead that Thumbtack is sending N
leadPrice string Estimated price that Pro will pay to Thumbtack N
chargeState string leadPrice Charge state value N

* There are a variety of possible schedule strings. The most common structure is as follows:

First line – Date or Dates. This could return a full date (e.g. "Fri Apr 10 2020") or just the month and day (e.g. "Apr 10"). If multiple dates, then comma-separated (e.g. "Apr 10, Apr 11, Apr 12")

Second line – Time or Times. This could return an exact time (e.g. "3:00 PM"), one time range (e.g. "Morning (9am - 12pm)"), or multiple time ranges (e.g. "Early Morning (before 9am), Morning (9am - 12pm), Afternoon (12pm - 3pm), Late Afternoon (3pm - 6pm)").

Third line - Length e.g. "4 hours".

** Some of our partners were onboarded before we added support for these fields. We do not send these fields to them without confirmation that they are ready to accept these fields. If you are one such partner and want to start getting these, please get in touch with us.

Lead Type Values

Possible values for the leadType field are mentioned below:

Lead Types
AVAILABILITY
CONTACT
ESTIMATION
CALL
BOOKING
PHONE_CONSULTATION
INSTANT_BOOK
SPONSORED
INSTANT_CONSULT
SERVICE_CALL
FULFILLMENT
REQUEST_A_QUOTE
MISMATCH_REQUEST_A_QUOTE

ChargeState Values

When leadPrice is null, you will get chargeState as null.

When leadPrice is non-null, you will get chargeState as Charged.

Messages

Sample Request Body

{
  "leadID": "299614694480093245",
  "customerID": "331138063184986319",
  "businessID": "286845156044809661",
  "message": {
    "messageID": "8699842694484326245",
    "createTimestamp": "1498760294",
    "text": "Do you offer fridge cleaning or is that extra?"
  }
}

Sample Request (assuming above JSON was saved as data.json)

curl -X POST https://www.api.[partner].com/v1/message
    -d data.json
    -H 'Content-Type:application/json'
    --user '<thumbtack_username>:<thumbtack_password>'

This endpoint will be called by Thumbtack to send messages to Partners. Messages will be coming from the Thumbtack customer to the Partner's Pro (represented as a business on Thumbtack).

Partners should return back 200 on successful processing of the messages. Sometimes messages might be delivered for leads that were created before the corresponding business was enabled in the API. In these cases, partners will not have seen that lead come through ProAPI before, and they should return 202.

HTTP Endpoint

POST https://api.[partner].com/v1/message

Note that the naming of this endpoint is flexible and dictated by the Partner.

Expected Request Body

Parameter Type Description Required
leadID string ID of the lead Y
customerID string ID of the customer who sent the message Y
businessID string ID of the business (pro) who is receiving the message Y
message object JSON message object Y
message.messageID string ID of the message Y
message.createTimestamp string Unix timestamp (seconds) of when message was created in UTC timezone Y
message.text string Text of the message Y

Update Lead

Sample Request Body

{
  "leadID": "465324000282984455",
  "leadPrice": "$26.00",
  "chargeState": "Charged",
}

Sample Request (assuming above JSON was saved as data.json)

curl -X PUT https://www.api.[partner].com/v1/lead/update
    -d data.json
    -H 'Content-Type:application/json'
    --user '<thumbtack_username>:<thumbtack_password>'

This endpoint will be called by Thumbtack to update the lead payload to Partners. Currently, lead price is generated after generating the leads, so Thumbtack needs a new updateLead API for sending updated payload to any Partner.

This update lead endpoint should be PUT.

HTTP Endpoint

PUT https://api.[partner].com/v1/lead/update

Note that the naming of this endpoint is flexible and dictated by the Partner.

Expected Request Body

Parameter Type Description Required
leadID string ID of the lead Y
leadPrice string Estimated price that Pro will pay to Thumbtack N
chargeState string leadPrice Charge state value N

ChargeState Values

When leadPrice is null, you will get chargeState as null.

When leadPrice is non-null, you will get chargeState as Charged.

Development Guide

Please follow the steps outlined in this section to integrate with Thumbtack's API.

Note that in order to call Thumbtack's test endpoints, Partners will need test credentials (username + password). Please contact us and we will get you set up with the appropriate test credentials.

Build Partner Endpoints

The first step is to build the endpoints outlined in the Partner Endpoints section.

Thumbtack supports both a test and production environment, so we recommend Partners to build both test and production endpoints as well. At a minimum, it is recommended that Partners test their endpoints by calling them (using curl or any similar tool) and validating that the endpoints return a successful HTTP 200 response.

The purpose of this is to ensure that the Partner endpoints can accept the payloads Thumbtack will provide. Feel free to use the sample request bodies provided throughout this guide to simulate the payloads Thumbtack will provide.

Create Test Data on Thumbtack

Sample Response

{
    "leadID": "380497493950742534",
    "createTimestamp": "1579643094",
    "price": "More information needed to give an estimate",
    "request": {
        "requestID": "380497492346044421",
        "category": "House Cleaning",
        "title": "House Cleaning",
        "description": "I am looking for someone to clean my apartment before I move",
        "schedule": "Date: Tue, May 05 2020\nTime: 6:00 PM\nLength: 3.5 hours",
        "location": {
            "city": "San Francisco",
            "state": "CA",
            "zipCode": "94103"
        },
        "travelPreferences": "Professional must travel to my address"
    },
    "customer": {
        "customerID": "380497491930800133",
        "name": "John Davis"
    },
    "business": {
        "businessID": "380497492389642246",
        "name": "Mr. Clean's Sparkly Cleaning Service"
    }
}

Sample Request

curl -X POST https://staging-pro-api.thumbtack.com/v1/test/create-lead
    -H 'Content-Type:application/json'
    --user '<thumbtack_username>:<thumbtack_password>'
    -d '{
        "businessID": <business_id>
    }'

Once you have successfully created your endpoints, the next step is to test calling Thumbtack's messages endpoint..

In order to do this, you will need to provide a valid businessID and leadID. By valid, we mean the businessID and leadID need to exist on Thumbtack. Thus, the Partner needs to create a dummy business and lead on Thumbtack's test environment.

To do this, we have provided an endpoint Partners can call to generate this dummy data.

HTTP Endpoint

POST https://staging-pro-api.thumbtack.com/v1/test/create-lead

Calling this endpoint will create a dummy business and lead on Thumbtack's test environment. On the right, we've provided a sample request and response. Note that passing in the Content-Type header is required.

Note: For the sample request, the businessID field is optional (although if you have been provided a businessID, it's recommended you provide it in the request. However, if you don't have a businessID you must provide an empty data payload.

Test Thumbtack Messaging Endpoint

Now that you've generated dummy data on Thumbtack's test environment, you should be able to test calling Thumbtack's messages endpoint.

Take the businessID and leadID that were returned from calling https://staging-pro-api.thumbtack.com/v1/test/create-lead and construct the appropriate Thumbtack messages endpoint.

In our case businessID is 380497492389642246 and leadID is 380497493950742534 so our Thumbtack messages endpoint would look like - https://api.thumbtack.com/v1/business/380497492389642246/lead/380497493950742534/message.

However, because we want to run this on our test environment, we want to use the staging-pro-api host instead of the api host. Thus, the endpoint we want to call would be https://staging-pro-api.thumbtack.com/v1/business/380497492389642246/lead/380497493950742534/message.

Call this endpoint as detailed in the Thumbtack's messages endpoint section, and validate that you get a success response.

Go To Production

At this point, the Partner's endpoints have been validated to accept Thumbtack payloads and the Partner has been able to successfully call Thumbtack's endpoint to send a message. The next step is to move the integration to Production.

To do this, the Partner needs to contact Thumbtack to set up Production credentials for the Partner's integration as well as inform Thumbtack about the Partner's endpoints. A Thumbtack representative will walk through the final steps to getting the Partner integrated onto the Thumbtack production environment.

Once a Partner has been fully set up on Production, Thumbtack will start pinging the Partner's endpoints when a Partner receives both leads and messages from Thumbtack customers. The Partner will be expected to ping Thumbtack's messages endpoint when they want to respond to a Thumbtack customer.

Contact Us

If you have any questions, feel free to reach out to us at partnerproducts-eng AT thumbtack DOT com

Authentication OAth2.0 Errors

400 Errors: StatusBadRequest

Error Code Description
INVALID_CLIENT Client authorization failed due to invalid or missing client ID provided
UNAUTHORIZED_CLIENT The client is not authorized to use this grant type
INVALID_REQUEST A request is missing a request parameter like, code, redirect_uri, refresh_token
INVALID_GRANT The provided authorization grant or refresh token is invalid, expired, revoked, or does not match the redirect URL
UNSUPPORTED_GRANT_TYPE The authorization grant_type provided in the request is not supported by the authorization server
INSUFFICIENT_SCOPE The request required higher privileges than provided by the access token
503 Service Unavailable -- We're temporarily unavailable to serve your request. Please try again later.

401 Errors: StatusUnauthorized

Error Code Description
INVALID_TOKEN The access token provided in the authorization header is not valid

403 Errors: StatusForBidden

Error Code Description
INSUFFICIENT_SCOPE The request required higher privileges than provided by the access token

Errors

The Thumbtack API uses the following error codes:

Error Code Description
400 Bad Request -- Something about your request was invalid or malformed.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The requested resource was not be found.
409 Conflict -- Something about your request conflicted with the current state of the server.
429 Too Many Requests -- You made too many requests, too quickly.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily unavailable to serve your request. Please try again later.

API Terms of Use

ACCEPTANCE OF THESE TERMS

This Terms of Use Agreement ("Terms") govern your access to, use of, and participation in the Thumbtack Pro API (the “API”) made available by Thumbtack, Inc. ("Thumbtack", "we", "our", or "us") and the entirety of your relationship with Thumbtack with respect thereto (except for any written agreements concerning other aspects of your relationship with us).

PLEASE READ THE TERMS THOROUGHLY AND CAREFULLY. BY USING THE API, YOU AGREE TO BE BOUND BY THESE TERMS. IF YOU DO NOT AGREE TO THESE TERMS, THEN YOU MAY NOT ACCESS OR USE THE API.

All references to "you" or "your," as applicable, mean the person (natural or otherwise) who accesses, uses, and/or participates in the API in any manner, and each of your heirs, assigns, and successors. If you use the API on behalf of an entity, you represent and warrant that you have the authority to bind that entity and your acceptance of the Terms will be deemed an acceptance by that entity, and "you" and "your" herein shall refer to that entity, its directors, affiliates, officers, employees, and agents. Terms used but not defined herein shall have the meanings ascribed to them in the Thumbtack Terms of Use, as they may exist at any given time at https://www.thumbtack.com/terms/ (the “Thumbtack Terms of Use”).

INCORPORATION BY REFERENCE

By your acceptance of these terms, you also agree to the following sections of the Thumbtack Terms of Use: “Arbitration and Class Action Waiver”, and “Governing Law”. Each of those sections are incorporated by reference herein, mutatis mutandis.

Further, you agree to conduct all interactions via the API in accordance with the Thumbtack Terms of Use, including the provisions on Eligibility, Service Member Representations, Warranties, And Use Of The Platform; and on Prohibitions, and such terms are incorporated by reference, mutatis mutandis, for such purpose. Your access to the API may be removed at any time, including in connection with any violation of such terms.

Thumbtack’s Privacy Policy, as it exists at any given time at https://www.thumbtack.com/privacy/, governs our use of the messages you send pursuant to the API and any other information you provide to Thumbtack.

MODIFICATIONS

Thumbtack reserves the right, in its sole discretion, to modify these Terms, and any other terms incorporated by reference herein, at any time with prompt notice to you. Thumbtack will notify you of changes by sending you a message or notifying you when you access the API. You agree that your continued use of the API after any such notice of modification constitutes your acceptance of such modification. If you do not agree to the modifications, you agree that you will not access or use the API.

API IMPLEMENTATION

You agree to use your commercially reasonable efforts to assist Thumbtack in its implementation of the API, including by implementing the technical specifications for accessing the API (the “API Documentation”) that Thumbtack provides to you. Thumbtack may deliver revised API Documentation to you from time to time and you hereby acknowledge that failure to implement any changes associated therewith may result in the API failing to function as contemplated.

API IMPAIRMENT

If you or any of your employees or other agents suspect the API’s functionality may be impaired, you will immediately inform Thumbtack. Thumbtack may, unless the applicable pro requests otherwise, pause any affected pro accounts on the Thumbtack platform and will investigate any such issues. Thumbtack makes no representation or warranty with respect to the availability of the API and shall not be liable for any down-time or impaired functionality with respect thereto. To the extent any API down-time was caused by Thumbtack, Thumbtack will use its commercially reasonable efforts to identify and refund any charges for contacts that were impacted by any down-time or other material (in Thumbtack’s discretion) API impairment.

API DATA

Service Professionals may use the API to transmit data to a third party (each, an “API CRM”), such as transmitting data to a Service Professional’s customer acquisition workflow, or customer relationship management service.. Any data transmitted pursuant to the API (“API Data”) is User Content subject to the Thumbtack Terms of Use and Thumbtack Privacy Policy. Personal information shared through the API, including communications between a Consumer and a Service Professional must be processed in compliance with all applicable privacy laws. Consumers share their personal information with a Service Professional, who receives such information as a “business”, controller or similar designation under applicable privacy laws. If you process API Data as an API CRM, you shall process such API Data solely to provide services to the applicable Service Professional and you will otherwise comply with all privacy laws concerning such personal information. Service Professionals who use the API to transmit API Data to an API CRM further represent and warrant they shall contractually require the API CRM to comply with applicable laws, including data privacy laws. Except as required by applicable law, all API Data shall be promptly destroyed by the API CRM (but in any case within 5 business days) if the API CRM ceases to use the API or upon Thumbtack’s reasonable request in connection with Thumbtack’s compliance with applicable law. You will hold the API Data and the API Documentation (to the extent not publicly posted) in strict confidence (in accordance with the terms of any confidentiality agreement signed between you and Thumbtack, if applicable).

Any data transmitted pursuant to the API (“API Data”) is User Content subject to the Thumbtack Terms of Use and Thumbtack Privacy Policy. Personal information shared through the API by a Consumer with a Service Professional must be treated by the Service Professional and by you in compliance with all applicable privacy laws. Consumers share their personal information with a Service Professional as a third party, controller or similar designation under applicable privacy laws; however, if you are providing services on behalf of such Service Professional, such personal information has not been shared with you other than in connection with the services you provide to such Service Professional and you therefore agree that you will only use such personal information to provide such services to such Service Professional and that you will otherwise comply with all privacy laws concerning such personal information. Except as required by applicable law, you will destroy all API Data promptly (but in any case within 5 business days) if you cease to use the API or upon Thumbtack’s reasonable request in connection with Thumbtack’s compliance with applicable law. You will hold the API Data and the API Documentation (to the extent not publicly posted) in strict confidence (in accordance with the terms of any confidentiality agreement signed between you and Thumbtack, if applicable).

If you become aware of any unauthorized access to API Data, you must immediately notify Thumbtack, consult and cooperate with investigations and potentially required notices, and promptly provide any information reasonably requested by Thumbtack. You must also indemnify Thumbtack from any resulting damages and costs, including, without limitation, identity protection assistance and services procured for data subjects and reasonable attorneys’ fees and costs and technical consultant fees incurred by Thumbtack in connection with any such incident.

INDEMNIFICATION

You agree to indemnify, defend and hold harmless Thumbtack, its directors, employees, representatives, officers and agents from and against any and all liability that may arise out of or in connection with your negligence, misconduct or fraud related to your use of the API, including but not limited to direct and indirect damages, losses, claims, costs, injuries, lost profits, loss of goodwill, property loss, property damage, personal injury, death, special damages, exemplary damages, consequential damages, punitive damages, and expenses (including but not limited to interest, attorney’s fees, and court costs).

LIMITATION OF LIABILITY

No party will be liable with respect to these Terms for (a) any incidental, special, exemplary or consequential damages, including lost profits, loss of data or loss of goodwill; (b) service interruption, computer damage or system failure; (c) the cost of substitute products or services; (d) any damages for personal or bodily injury or emotional distress arising out of or in connection with these terms; (e) the use of or inability to use the API or the Thumbtack platform; (f) any communications, interactions or meetings with users of the Thumbtack platform or other persons with whom you communicate or interact with as a result of your use of the API; or (g) you or, if applicable, your client’s offering or providing pro services through the Thumbtack platform. Notwithstanding the foregoing, your obligations under the “Indemnification” and “API Data” sections above are excluded from the foregoing sentence.

SPECIAL REPRESENTATIONS FOR CRM SERVICES

If you are acting as a customer relationship management or similar service on behalf of a Thumbtack service professional you hereby agree that (i) nothing in these Terms alters the relationship between Thumbtack and any such service professional, (ii) when accessing the API and API Data, you are acting solely as an agent of such service professional, and (iii) Thumbtack is not selling you any data.

shell