Overview
Getting Started
Widgets
Categories
Keywords
Reviews
Users
Businesses
Businesses Search
Negotiations
Messages
Requests
Help
Changelog
Terms and Policies
Follow along with a fully worked use case on how to leverage the Businesses Search API, along with the Categories API and Requests API.
- An OAuth2 Client that supports the clientCredentials Flow with the following scopes:
- demand::categories/request-form.read
- demand::businesses/search.read
- An OAuth2 Client that supports the authorizationCode Flow with the following scopes:
- demand::requests.write
The first step in the Exact Search flow is to fetch the Request Form for the given Category you wish to fetch Businesses for. For this worked example, let's consider that your User wishes to have some kitchen remodeling work done (categoryID: 201565295100608806).
We issue the following request, and capture the response:
GET /api/v4/categories/201565295100608806/request-form HTTP/2authorization: Bearer {{clientCredentials}}
{"requestFormID": "360027128293056514","questions": [{"questionID": "326918438863339640","inputType": "default","prompt": "What kind of work would you like done?","questionType": "checkboxOption","answers": [{"answerID": "316487650924830878","value": "Repair of existing tiling or flooring","type": "selectionOption"},{"answerID": "316487650997280931","value": "Repair of existing cabinetry or fixtures","type": "selectionOption"},{"answerID": "316487651066650683","value": "Installation of new tiling or flooring","type": "selectionOption"},{"answerID": "316487651135701155","value": "Installation of new cabinetry or fixtures","type": "selectionOption"},{"answerID": "316487651200925747","value": "Full remodel of existing kitchen","type": "selectionOption"},{"answerID": "316487651281379486","value": "Construction of new kitchen","type": "selectionOption"}],"validationConstraints": {"minimumAnswersSelected": 1,"maximumAnswersSelected": 6,"minimumAnswerLength": 0,"maximumAnswerLength": 16384}},{"questionID": "326918488383725680","inputType": "default","prompt": "Will any plumbing need to be relocated?","questionType": "radioOption","answers": [{"answerID": "325366687356805247","value": "No, plumbing will not need to be relocated","type": "selectionOption"},{"answerID": "316488145036181679","value": "Yes, plumbing will need to be relocated","type": "selectionOption"},{"answerID": "316488145100554403","value": "I'm not sure, need professional recommendation","type": "selectionOption"}],"validationConstraints": {"minimumAnswersSelected": 1,"maximumAnswersSelected": 1,"minimumAnswerLength": 0,"maximumAnswerLength": 16384}},{"questionID": "326918523791990896","inputType": "default","prompt": "Will any electrical outlets need to be relocated?","questionType": "radioOption","answers": [{"answerID": "325366748075507781","value": "No, electrical will not need to be relocated","type": "selectionOption"},{"answerID": "316488505428279318","value": "Yes, electrical will need to be relocated","type": "selectionOption"},{"answerID": "316488505501212830","value": "I'm not sure, need professional recommendation","type": "selectionOption"}],"validationConstraints": {"minimumAnswersSelected": 1,"maximumAnswersSelected": 1,"minimumAnswerLength": 0,"maximumAnswerLength": 16384}},{"questionID": "326918624526221502","inputType": "default","prompt": "Do you have existing plans?","questionType": "radioOption","answers": [{"answerID": "326138048477724682","value": "No existing plans, but have a good idea of what I want","type": "selectionOption"},{"answerID": "326138048605896801","value": "No existing plans - need design suggestions","type": "selectionOption"},{"answerID": "326918624407994379","value": "Already have plans - just need installation","type": "selectionOption"}],"validationConstraints": {"minimumAnswersSelected": 1,"maximumAnswersSelected": 1,"minimumAnswerLength": 0,"maximumAnswerLength": 16384}},{"questionID": "316466600777244731","inputType": "default","prompt": "What type of property do you have?","questionType": "radioOption","answers": [{"answerID": "306287244499165254","value": "Residential","type": "selectionOption"},{"answerID": "306287244500426981","value": "Commercial","type": "selectionOption"}],"validationConstraints": {"minimumAnswersSelected": 1,"maximumAnswersSelected": 1,"minimumAnswerLength": 0,"maximumAnswerLength": 16384}},{"questionID": "354563000779964436","inputType": "default","prompt": "What other info should we pass along?","subprompt": "Additional details help pros provide the right recommendations, prices and service.","questionType": "multipleLineText","validationConstraints": {"minimumAnswersSelected": 0,"maximumAnswersSelected": 1,"minimumAnswerLength": 0,"maximumAnswerLength": 16384}},{"questionID": "360027125915131908","inputType": "default","prompt": "Please enter the zip code where you need the kitchen remodel contractor.","questionType": "singleLineText","validationConstraints": {"minimumAnswersSelected": 1,"maximumAnswersSelected": 1,"minimumAnswerLength": 5,"maximumAnswerLength": 5}},{"questionID": "90114","inputType": "phoneNumber","prompt": "Let’s get your contact info.","subprompt": "Your number’s hidden until you and the pro decide on a time.","questionType": "singleLineText","validationConstraints": {"minimumAnswersSelected": 1,"maximumAnswersSelected": 1,"minimumAnswerLength": 14,"maximumAnswerLength": 14,"answerRegexPattern": "^\\(\\d{3}\\) \\d{3}-\\d{4}$"}},{"questionID": "90115","prompt": "Can we send you text messages?","questionType": "checkboxOption","answers": [{"answerID": "10044","value": "Text me updates","type": "selectionOption","isDefault": true}],"validationConstraints": {"minimumAnswersSelected": 0,"maximumAnswersSelected": 1}}]}
With the Request Form returned above, you can render this to your Users to allow them to specify answers to the Request Form. Once they have entered all their answers, you can include this as an input when searching for Businesses. For our example below, let's assume this User:
- What kind of work would you like done? -> Repair of existing tiling or flooring
- Will any plumbing need to be relocated? -> No, plumbing will not need to be relocated
- Will any electrical outlets need to be relocated? -> Yes, electrical will need to be relocated
- Do you have existing plans? -> No existing plans, but have a good idea of what I want
- What type of property do you have? -> Residential
- What other info should we pass along? -> Nothing
- Please enter the zip code where you need the kitchen remodel contractor. -> 90210
- Let’s get your contact info. -> (555) 555-5555
- Can we send you text messages? -> [] (Default is true)
We issue the following request, and capture the response:
POST /api/v4/businesses/search HTTP/2authorization: Bearer {{clientCredentials}}content-type: application/json{"categoryID": "201565295100608806","zipCode": "94117","limit": 10,"utmData": {"utm_source": "cma-admin"},"requestFormDetails": {"requestFormID": "360027128293056514","requestFormAnswers": [{"questionID": "326918438863339640","answerIDs": ["316487650924830878"]},{"questionID": "326918488383725680","answerIDs": ["325366687356805247"]},{"questionID": "326918523791990896","answerIDs": ["316488505428279318"]},{"questionID": "326918624526221502","answerIDs": ["326138048477724682"]},{"questionID": "316466600777244731","answerIDs": ["306287244499165254"]},{"questionID": "354563000779964436","freeFormAnswer": ["Nothing"]},{"questionID": "360027125915131908","freeFormAnswer": ["94117"]},{"questionID": "90114","freeFormAnswer": ["(555) 555-5555"]},{"questionID": "90115","answerIDs": []}]}}
{"searchID": "548954743629463556","data": [{"businessID": "468046965846925323","businessName": "Igreen Builders Inc","businessIntroduction": "We are a Green Design-Build company with trained project managers on staff who can help our customers take a project from an idea to completion with a hassle-free experience. IGreen Builders provides fair pricing for the best quality work, and our main goal is to accomplish 100% customer satisfaction with the performance and services provided without cutting any corners. We are honest, patient, and we listen to our customers to deliver the best results as deserve!! We are proud to be a leading 5-star rated company in the Bay Area and are A+ accredited with the BBB. We are looking forward to serving you!","quote": {"startingCost": 0,"costUnit": "on-site estimate"},"businessLocation": "Milpitas, CA","numberOfEmployees": 45,"numberOfSimilarJobsDone": 0,"isTopPro": false,"rating": 5,"numberOfReviews": 11,"featuredReview": "My wife and I bought a beautiful home this year and everything but the kitchen was great so we decided to remodel in October of this year. After speaking with various local companies we decided to work with IGreen Builders because of the attention to detail they gave us. Communication is fluid and honest, and our experience has been very personalized and realistic. A true partner throughout the entire process and now our kitchen is exactly what we envisioned. Thank you IGreen Team for making that happen!","yearsInBusiness": 7,"numberOfHires": 4,"responseTimeHours": 0,"servicePageURL": "https://thumbtack.com/ca/milpitas/general-contractors/igreen-builders-inc/service/468046965846925323?category_pk=201565295100608806&project_pk=548954743629463556&search_query=201565295100608806&utm_medium=partnership&utm_source=cma-admin&utm_tt_session=61537f21b187ce85b593e64fb87ff9fc019ccc9a651e86ba20e82eb180a8f235&zip_code=94117","businessImageURL": "https://production-next-images-cdn.thumbtack.com/i/505012430491254790/desktop/standard/profile-legacy","pills": ["low_price","licensed"],"isBusinessLicenseVerified": true,"isBackgroundChecked": true,"widgets": {"requestFlowURL": "https://thumbtack.com/embed/request-flow?category_pk=201565295100608806&page_source=admin&project_pk=548954743629463556&search_query=201565295100608806&service_pk=468046965846925323&utm_medium=partnership&utm_source=cma-admin&utm_tt_session=61537f21b187ce85b593e64fb87ff9fc019ccc9a651e86ba20e82eb180a8f235&zip_code=94117","servicePageURL": "https://thumbtack.com/ca/milpitas/general-contractors/igreen-builders-inc/service/468046965846925323?category_pk=201565295100608806&project_pk=548954743629463556&search_query=201565295100608806&utm_medium=partnership&utm_source=cma-admin&utm_tt_session=61537f21b187ce85b593e64fb87ff9fc019ccc9a651e86ba20e82eb180a8f235&zip_code=94117"}},{"businessID": "499124195567230988","businessName": "IY Development Inc","businessIntroduction": "With over 12 years of experience, our family-owned general contracting business is dedicated to providing homeowners throughout the Bay Area with exceptional customer service and high-end craftsmanship. From new construction to home additions, kitchen remodeling, and bathroom remodeling, we bring expertise and passion to every project. Our commitment to personalized experiences ensures that each client receives tailored solutions that exceed expectations. Trust our experienced team to transform your vision into reality, delivering outstanding results that will enhance your home","quote": {"startingCost": 0,"costUnit": "on-site estimate"},"businessLocation": "San Francisco, CA","numberOfEmployees": 10,"numberOfSimilarJobsDone": 0,"isTopPro": false,"rating": 5,"numberOfReviews": 10,"featuredReview": "IY Development recently completed a full bathroom remodel for me in San Francisco, and I couldn't be more thrilled with the results!Adam, the owner, was fantastic to work withtransparent, responsive, and genuinely invested in making sure everything turned out perfectly. The team was also professional, skilled, and respectful of my home throughout the entire process.What really set IY Development apart was that they took care of everythingfrom design suggestions to handling all the necessary permits and inspections, which made the project completely stress-free for me. The final result is stunning!If you're looking for high-quality contractor and a team you can trust, I highly recommend IY Development!","yearsInBusiness": 5,"numberOfHires": 4,"responseTimeHours": 1.9927874444444444,"servicePageURL": "https://thumbtack.com/ca/san-francisco/general-contractors/iy-development-inc/service/499124195567230988?category_pk=201565295100608806&project_pk=548954743629463556&search_query=201565295100608806&utm_medium=partnership&utm_source=cma-admin&utm_tt_session=61537f21b187ce85b593e64fb87ff9fc019ccc9a651e86ba20e82eb180a8f235&zip_code=94117","businessImageURL": "https://production-next-images-cdn.thumbtack.com/i/499124538585104392/desktop/standard/profile-legacy","pills": ["low_price","licensed"],"isBusinessLicenseVerified": true,"isBackgroundChecked": true,"widgets": {"requestFlowURL": "https://thumbtack.com/embed/request-flow?category_pk=201565295100608806&page_source=admin&project_pk=548954743629463556&search_query=201565295100608806&service_pk=499124195567230988&utm_medium=partnership&utm_source=cma-admin&utm_tt_session=61537f21b187ce85b593e64fb87ff9fc019ccc9a651e86ba20e82eb180a8f235&zip_code=94117","servicePageURL": "https://thumbtack.com/ca/san-francisco/general-contractors/iy-development-inc/service/499124195567230988?category_pk=201565295100608806&project_pk=548954743629463556&search_query=201565295100608806&utm_medium=partnership&utm_source=cma-admin&utm_tt_session=61537f21b187ce85b593e64fb87ff9fc019ccc9a651e86ba20e82eb180a8f235&zip_code=94117"}}],"metadata": {"categoryID": "201565295100608806","categoryName": "Kitchen Remodel","categoryImageURL": "https://production-next-images-cdn.thumbtack.com/i/323234790910238847/small/standard/hero","zipCode": "94117","requestLocation": "San Francisco, CA","seeMoreProsURL": "https://thumbtack.com/instant-results/?category_pk=201565295100608806&project_pk=548954743629463556&utm_medium=partnership&utm_source=cma-admin&utm_tt_session=61537f21b187ce85b593e64fb87ff9fc019ccc9a651e86ba20e82eb180a8f235&zipCode=94117&zip_code=94117"}}
Now that we have our list of Businesses, we can return said Businesses to the User to allow them to select which Business(es) to book.
Once they have decided, we can then create a Request, which, if successful, will return a 201 Created status code.
POST /api/v4/requests HTTP/2authorization: Bearer {{authorizationCode}}content-type: application/json{"searchID": "548954743629463556","serviceIDs": ["468046965846925323"],"categoryID": "201565295100608806","utmData": {"utm_source": "cma-admin"}}
{"request": {"requestID": "548955282027569156","customerID": "498954473003245570","description": "Nothing","category": {"categoryID": "201565295100608806","name": "Kitchen Remodel"},"proposedTimes": [],"location": {"address1": "","address2": "","city": "San Francisco","state": "CA","zipCode": "94117"},"travelPreferences": ["Professional must travel to my address."],"details": [{"question": "Category","answer": "Kitchen Remodel"},{"question": "Travel Preferences","answer": "The kitchen remodel contractor travels to me"},{"question": "Property type","answer": "Residential"},{"question": "Project scope","answer": "Repair of existing tiling or flooring"},{"question": "Plumbing to be relocated","answer": "No, plumbing will not need to be relocated"},{"question": "Electrical to be relocated","answer": "Yes, electrical will need to be relocated"},{"question": "Existing plans","answer": "No existing plans, but have a good idea of what I want"},{"question": "Anything else","answer": "Nothing"},{"question": "Zip code","answer": "94117"}],"attachments": []},"contactErrors": []}