Request Schemas StartJobRequest Schema for initiating a new service job.
User’s free text query describing the service needed (e.g., “fix my toilet”)
Full house address where the service is needed
User’s ZIP code for provider matching
Dollar amount budget limit or the string “no_limit”
Date when service is needed in ISO format (e.g., “2025-12-10”)
Example: { "query" : "fix my toilet" , "house_address" : "123 Main St, San Jose, CA 95126" , "zip_code" : "95126" , "price_limit" : 250 , "date_needed" : "2025-12-10" }
CompleteJobRequest Schema for completing a job after answering clarifying questions.
The job ID returned from the start-job endpoint
Dictionary mapping question IDs to answer strings
Example: { "job_id" : "abc123" , "answers" : { "q1" : "The toilet is constantly running" , "q2" : "Standard toilet, not smart" , "q3" : "First floor bathroom" } }
Response Schemas StartJobResponse Response returned when starting a new job.
Unique identifier for the created job (UUID format)
Extracted task category (e.g., “plumber”, “electrician”)
Array of clarifying questions to gather more details Unique identifier for the question (e.g., “q1”, “q2”)
The clarifying question text
Example: { "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "task" : "plumber" , "questions" : [ { "id" : "q1" , "question" : "What is the specific issue with your toilet?" }, { "id" : "q2" , "question" : "Is your toilet running constantly or leaking?" }, { "id" : "q3" , "question" : "How old is your toilet?" }, { "id" : "q4" , "question" : "Have you noticed any water damage around the toilet?" }, { "id" : "q5" , "question" : "Is this an emergency or can it wait a day?" } ] }
CompleteJobResponse Response returned when completing a job with matched providers.
The complete job object with all collected information Unique job identifier (UUID format)
Original user query from the start-job request
Extracted task category (e.g., “plumber”, “electrician”)
Full house address for the service
ZIP code for provider matching
Date when service is needed (ISO format)
Budget limit as dollar amount or “no_limit”
Dictionary of question IDs mapped to user answers
Array of ClarifyingQuestion objects (typically empty after completion)
Current job status: “collecting_info”, “ready_for_search”, or “searched”
Array of matched service providers Unique provider database identifier
Provider phone number (optional)
Estimated service price (optional, populated after provider contact)
Final negotiated price (optional, populated after negotiation)
Status of provider contact attempt (optional)
Example: { "job" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "original_query" : "fix my toilet" , "task" : "plumber" , "house_address" : "123 Main St, San Jose, CA 95126" , "zip_code" : "95126" , "date_needed" : "2025-12-10" , "price_limit" : 250 , "clarifications" : { "q1" : "The toilet is constantly running" , "q2" : "Standard toilet, about 10 years old" }, "questions" : [], "status" : "searched" }, "providers" : [ { "id" : 1 , "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Mike's Plumbing Services" , "phone" : "(408) 555-1234" , "estimated_price" : null , "negotiated_price" : null , "call_status" : null }, { "id" : 2 , "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Bay Area Plumbers" , "phone" : "(408) 555-5678" , "estimated_price" : null , "negotiated_price" : null , "call_status" : null } ] }
Enums JobStatus Status values for job lifecycle tracking.
Value Description collecting_infoInitial state, gathering clarifying information ready_for_searchInformation collected, ready to search for providers searchedProvider search completed, results available
Supporting Schemas ClarifyingQuestion Represents a question to gather additional job details.
Unique question identifier (e.g., “q1”, “q2”, “q3”)
The question text to display to the user
ProviderBase Base provider information from search results.
Provider phone number (optional)
ProviderCreate Schema for creating a new provider record in the database.
Provider phone number (optional)