Overview Provider endpoints allow you to retrieve service provider information, monitor call status, and trigger automated negotiation calls.
List All Providers Retrieves all providers in the database across all jobs. Primarily used for debugging.
Response Returns an array of provider objects:
Database ID of the provider.
Provider’s business name.
Example Request curl http://localhost:8000/api/providers
Example Response [ { "id" : 1 , "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Mike's Plumbing Services" , "phone" : "(408) 555-1234" }, { "id" : 2 , "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Bay Area Plumbers" , "phone" : "(408) 555-5678" } ]
Get Providers by Job GET /api/providers/{job_id}
Retrieves all providers associated with a specific job.
Path Parameters The job ID to retrieve providers for.
Response Provider’s business name.
Final negotiated price (null until call completes).
Current call status. Default: "pending"
Example Request curl http://localhost:8000/api/providers/550e8400-e29b-41d4-a716-446655440000
Example Response [ { "id" : 1 , "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Reliable Plumbing Services" , "phone" : "(408) 555-0101" , "estimated_price" : 150.0 , "negotiated_price" : 135.0 , "call_status" : "completed" }, { "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" } ]
Get Provider Status GET /api/providers/{job_id}/status
Retrieves provider information with call status and negotiated prices. Optimized for frontend polling to track negotiation progress.
Path Parameters The job ID to retrieve provider status for.
Response Show Provider status object
Provider’s business name.
Final negotiated price after call.
Current status of the automated call. Possible values: "pending", "in_progress", "completed", "failed"
Full transcript of the negotiation call (if available).
Example Request curl http://localhost:8000/api/providers/550e8400-e29b-41d4-a716-446655440000/status
Example Response [ { "id" : 1 , "job_id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Reliable Plumbing Services" , "phone" : "(408) 555-0101" , "estimated_price" : 150.0 , "negotiated_price" : 135.0 , "call_status" : "completed" , "call_transcript" : "Agent: Hello, this is regarding a plumbing job... \n Provider: Yes, I can help with that... \n ..." }, { "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" : "in_progress" , "call_transcript" : null } ]
Usage Pattern This endpoint is designed for polling:
// Poll every 5 seconds for updates const pollStatus = async ( jobId ) => { const response = await fetch ( `http://localhost:8000/api/providers/ ${ jobId } /status` ); const providers = await response . json (); // Check if all calls are complete const allComplete = providers . every ( p => p . call_status === 'completed' || p . call_status === 'failed' ); if ( ! allComplete ) { setTimeout (() => pollStatus ( jobId ), 5000 ); } };
Start Calls POST /api/start-calls/{job_id}
Triggers automated negotiation calls for all providers associated with a job. Calls the backend service (runs on port 6000) to initiate the voice agent calls.
Path Parameters The job ID to start calls for.
Response Status of the call initiation. Value: "started"
Human-readable message about the operation.
Number of providers that calls were initiated for.
Example Request curl -X POST http://localhost:8000/api/start-calls/550e8400-e29b-41d4-a716-446655440000
Example Response { "status" : "started" , "message" : "Started calls for 3 providers" , "provider_count" : 3 }
Error Responses { "detail" : "Job not found: 550e8400-e29b-41d4-a716-446655440000" }
{ "detail" : "No providers found for job: 550e8400-e29b-41d4-a716-446655440000" }
503 - Service Unavailable
{ "detail" : "Call backend service unavailable: Connection refused" }
Configuration The call backend URL can be configured via environment variable:
CALL_BACKEND_URL = http://localhost:6000
Default: http://localhost:6000Implementation Details This endpoint:
Verifies the job exists in memory
Verifies providers exist in the database for this job
Makes an HTTP POST request to {CALL_BACKEND_URL}/start-job/{job_id}
Returns success status and provider count
The backend service handles:
Initiating voice agent calls to each provider
Conducting automated negotiation
Updating provider records with negotiated prices and call status
Storing call transcripts