Endpoint Description Completes a job by submitting answers to clarifying questions and triggers provider search. This endpoint:
Retrieves the job from in-memory storage using job_id
Merges clarification answers into the job object
Builds a search prompt from the complete job context
Calls Grok Fast Search to find relevant service providers
Saves providers to Supabase database with normalized data
Returns the updated job object and list of matched providers
Request Body The job ID returned from the /api/start-job endpoint. Example: "550e8400-e29b-41d4-a716-446655440000"
Dictionary mapping question IDs to user’s answers. Keys should match the question id values from the start-job response. Example: { "q1" : "The toilet is constantly running" , "q2" : "Yes, water runs non-stop" , "q3" : "About 10 years old" , "q4" : "No water damage visible" , "q5" : "Not an emergency, can wait a day" }
Response The complete job object with all details and updated status. The job’s unique identifier.
The user’s original service request query.
The inferred task/service type (e.g., “plumber”).
Full service location address.
ZIP code for the service location.
When the service is needed.
Maximum price or “no_limit”.
Dictionary of question IDs to user answers.
Array of ClarifyingQuestion objects from start-job.
Job status. Will be "searched" after successful completion. Possible values: "collecting_info", "ready_for_search", "searched"
Array of matched service providers found via Grok Fast Search. Database ID of the provider record.
The job ID this provider is associated with.
Service provider’s business name. Example: "Reliable Plumbing Services"
Provider’s phone number. Example: "(408) 555-0101"
Estimated price for the service (may be null initially).
Final negotiated price after call (null until negotiation completes).
Status of the automated call to this provider. Default: "pending"
Example Request curl -X POST http://localhost:8000/api/complete-job \ -H "Content-Type: application/json" \ -d '{ "job_id": "550e8400-e29b-41d4-a716-446655440000", "answers": { "q1": "The toilet is constantly running", "q2": "Yes, water runs non-stop", "q3": "About 10 years old", "q4": "No water damage visible", "q5": "Not an emergency, can wait a day" } }'
Example Response { "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" : "Yes, water runs non-stop" }, "questions" : [ { "id" : "q1" , "question" : "What is the specific issue with your toilet?" }, { "id" : "q2" , "question" : "Is the toilet running constantly or leaking?" } ], "status" : "searched" }, "providers" : [ { "id" : 1 , "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Reliable Plumbing Services" , "phone" : "(408) 555-0101" , "estimated_price" : 150.0 , "negotiated_price" : null , "call_status" : "pending" }, { "id" : 2 , "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Bay Area Plumbers" , "phone" : "(408) 555-5678" , "estimated_price" : 200.0 , "negotiated_price" : null , "call_status" : "pending" } ] }
Error Responses { "detail" : "Job not found: 550e8400-e29b-41d4-a716-446655440000" }
{ "detail" : "Error completing job: Grok Fast Search API unavailable" }
Implementation Details Provider Search Process
Context Formatting : Answers are formatted into a natural paragraph for contextProblem Statement : Grok LLM generates a formatted problem statement from the query and taskSearch Query : Complete job context (task, location, answers) is sent to Grok Fast SearchProvider Normalization : Search results are parsed and normalized into provider recordsDatabase Storage : Each provider is saved to Supabase with:
Job ID and provider details (name, phone)
Context answers paragraph
Problem statement
Location data (address, ZIP)
Price constraints
Initial call status (“pending”)
Data Persistence
Job : Updated in-memory only (status changes to "searched")Providers : Persisted to Supabase database for tracking throughout the negotiation process
Next Steps After receiving providers, you can:
Use POST /api/start-calls/ to initiate automated calls
Poll GET /api/providers//status to track call progress and negotiated prices