Procedure Bid APIs

Overview

The Procedure Bid APIs enable a marketplace where patients can request bids for medical procedures and clinics/healthcare providers can submit competitive bids. This system facilitates price discovery and service quality competition.

Authentication

All API requests require authentication using valid JWT tokens:

Patients: Access bid request endpoints
Clinics/Doctors: Access bid submission endpoints
Include Authorization: Bearer <jwt_token> header

Patient Bid Request APIs

Create Procedure Bid Request

Endpoint: POST {{url}}/patients/{patient_id}/procedure_bid_requests

Description: Create a new bid request for a medical procedure. Patients can specify their requirements, budget, timeline, and other preferences.

Request Body:

{
  "patient_id": 8,
  "basic_procedure_id": 8,
  "urgency_level": "urgent",
  "preferred_timestamp": "2025-01-15T10:00:00Z",
  "bid_deadline": "2025-01-10T18:00:00Z",
  "max_bids": 5,
  "minimum_rating": 4.0,
  "anonymous_bidding": true,
  "auto_select_best_bid": false,
  "location_scope": "domestic",
  "max_travel_distance": 50,
  "include_travel_package": false,
  "min_budget": 5000,
  "max_budget": 15000,
  "include_financing": true,
  "insurance_provider": "HealthPlus Insurance",
  "insurance_policy_number": "HP-123456789",
  "past_history": "Previous physiotherapy sessions provided temporary relief",
  "additional_requirements": "Looking for a clinic with post-operative rehabilitation facilities",
  "contact_preference": "email"
}

Parameters:

Parameter	Type	Required	Description
`patient_id`	Integer	Yes	Patient identifier
`basic_procedure_id`	Integer	Yes	Medical procedure identifier from basic_procedures table
`urgency_level`	String	Yes	Urgency level: `"urgent"`, `"flexible"`, `"routine"`
`preferred_timestamp`	DateTime	Yes	Preferred procedure date/time (ISO 8601 format)
`bid_deadline`	DateTime	Yes	Deadline for bid submissions
`max_bids`	Integer	No	Maximum number of bids to accept (default: 10)
`minimum_rating`	Float	No	Minimum doctor rating requirement (0.0-5.0)
`anonymous_bidding`	Boolean	No	Hide patient identity from bidders (default: false)
`auto_select_best_bid`	Boolean	No	Automatically select best bid when deadline passes
`location_scope`	String	No	Geographic scope: `"local"`, `"domestic"`, `"international"`
`max_travel_distance`	Integer	No	Maximum travel distance in kilometers
`include_travel_package`	Boolean	No	Include travel/accommodation in bid
`min_budget`	Integer	No	Minimum budget amount
`max_budget`	Integer	No	Maximum budget amount
`include_financing`	Boolean	No	Require financing options
`insurance_provider`	String	No	Insurance company name
`insurance_policy_number`	String	No	Insurance policy number
`past_history`	Text	No	Patient's medical history relevant to procedure
`additional_requirements`	Text	No	Special requirements or preferences
`contact_preference`	String	No	Preferred contact method: `"email"`, `"phone"`, `"sms"`

Response (201 Created):

{
  "success": true,
  "data": {
    "id": 1,
    "patient_id": 8,
    "basic_procedure_id": 8,
    "urgency_level": "urgent",
    "status": "open",
    "preferred_timestamp": "2025-01-15T10:00:00Z",
    "bid_deadline": "2025-01-10T18:00:00Z",
    "max_bids": 5,
    "current_bids_count": 0,
    "minimum_rating": 4.0,
    "anonymous_bidding": true,
    "auto_select_best_bid": false,
    "location_scope": "domestic",
    "max_travel_distance": 50,
    "min_budget": 5000,
    "max_budget": 15000,
    "include_financing": true,
    "insurance_provider": "HealthPlus Insurance",
    "past_history": "Previous physiotherapy sessions provided temporary relief",
    "additional_requirements": "Looking for a clinic with post-operative rehabilitation facilities",
    "contact_preference": "email",
    "created_at": "2025-01-08T10:00:00Z",
    "updated_at": "2025-01-08T10:00:00Z",
    "basic_procedure": {
      "id": 8,
      "name": "Arthroscopic Knee Surgery",
      "category": "Orthopaedic Surgery"
    }
  },
  "message": "Bid request created successfully"
}

Error Responses:

400 Bad Request: Invalid parameters
401 Unauthorized: Invalid or missing authentication
404 Not Found: Patient or procedure not found
422 Unprocessable Entity: Validation errors

Update Procedure Bid Request

Endpoint: PUT {{url}}/patients/{patient_id}/procedure_bid_requests/{id}

Description: Update an existing bid request. Only requests with "open" status can be updated.

Request Body:

{
  "patient_id": 8,
  "basic_procedure_id": 8,
  "urgency_level": "flexible",
  "preferred_timestamp": "2025-01-20T14:00:00Z",
  "bid_deadline": "2025-01-12T18:00:00Z",
  "max_bids": 8,
  "minimum_rating": 4.5,
  "anonymous_bidding": true,
  "auto_select_best_bid": false,
  "location_scope": "domestic",
  "max_travel_distance": 75,
  "include_travel_package": true,
  "min_budget": 6000,
  "max_budget": 18000,
  "include_financing": true,
  "insurance_provider": "HealthPlus Insurance",
  "insurance_policy_number": "HP-123456789",
  "past_history": "Previous physiotherapy sessions provided temporary relief",
  "additional_requirements": "Looking for a clinic with post-operative rehabilitation facilities and weekend availability",
  "contact_preference": "email"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "patient_id": 8,
    "basic_procedure_id": 8,
    "urgency_level": "flexible",
    "status": "open",
    "preferred_timestamp": "2025-01-20T14:00:00Z",
    "bid_deadline": "2025-01-12T18:00:00Z",
    "max_bids": 8,
    "current_bids_count": 2,
    "minimum_rating": 4.5,
    "updated_at": "2025-01-08T11:30:00Z"
  },
  "message": "Bid request updated successfully"
}

Error Responses:

400 Bad Request: Invalid parameters
401 Unauthorized: Invalid authentication
403 Forbidden: Cannot update request after bidding started
404 Not Found: Bid request not found

List Patient Bid Requests

Endpoint: GET {{url}}/patients/{patient_id}/procedure_bid_requests

Description: Retrieve all bid requests for a specific patient with optional filtering and pagination.

Query Parameters:

page: Page number (default: 1)
per_page: Items per page (default: 20, max: 100)
status: Filter by status ("open", "closed", "accepted", "expired")
urgency_level: Filter by urgency level

Example Request: GET {{url}}/patients/8/procedure_bid_requests?page=1&per_page=10&status=open

Response (200 OK):

{
  "success": true,
  "data": {
    "procedure_bid_requests": [
      {
        "id": 1,
        "basic_procedure_id": 8,
        "urgency_level": "urgent",
        "status": "open",
        "preferred_timestamp": "2025-01-15T10:00:00Z",
        "bid_deadline": "2025-01-10T18:00:00Z",
        "current_bids_count": 3,
        "max_bids": 5,
        "min_budget": 5000,
        "max_budget": 15000,
        "created_at": "2025-01-08T10:00:00Z",
        "basic_procedure": {
          "id": 8,
          "name": "Arthroscopic Knee Surgery",
          "category_name": "Orthopaedic Surgery"
        }
      }
    ],
    "total_pages": 1,
    "total_records": 1,
    "current_page": 1
  }
}

Get Bid Request Details

Endpoint: GET {{url}}/patients/{patient_id}/procedure_bid_requests/{id}

Description: Retrieve detailed information about a specific bid request including all submitted bids.

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "patient_id": 8,
    "basic_procedure_id": 8,
    "urgency_level": "urgent",
    "status": "open",
    "preferred_timestamp": "2025-01-15T10:00:00Z",
    "bid_deadline": "2025-01-10T18:00:00Z",
    "max_bids": 5,
    "current_bids_count": 3,
    "minimum_rating": 4.0,
    "anonymous_bidding": true,
    "min_budget": 5000,
    "max_budget": 15000,
    "past_history": "Previous physiotherapy sessions provided temporary relief",
    "additional_requirements": "Looking for a clinic with post-operative rehabilitation facilities",
    "created_at": "2025-01-08T10:00:00Z",
    "basic_procedure": {
      "id": 8,
      "name": "Arthroscopic Knee Surgery",
      "description": "Minimally invasive surgical procedure to diagnose and treat problems in the knee joint",
      "category_name": "Orthopaedic Surgery"
    },
    "procedure_bids": [
      {
        "id": 1,
        "clinic_id": 3,
        "doctor_id": 1,
        "offered_price": 12000,
        "currency": "INR",
        "proposed_timeline": "Procedure can be scheduled within 2 weeks of confirmation",
        "status": "pending",
        "notes": "Experienced orthopaedic surgeon with 15+ years of practice. State-of-the-art facility.",
        "created_at": "2025-01-08T11:00:00Z",
        "clinic": {
          "id": 3,
          "name": "City Orthopaedic Centre",
          "city": "Mumbai",
          "rating": 4.7
        },
        "doctor": {
          "id": 1,
          "name": "Dr. Rajesh Kumar",
          "speciality": "Orthopaedic Surgery",
          "rating": 4.8,
          "experience": 15
        }
      }
    ]
  }
}

Delete Bid Request

Endpoint: DELETE {{url}}/patients/{patient_id}/procedure_bid_requests/{id}

Description: Delete a bid request. Only requests with "open" status and no accepted bids can be deleted.

Response (200 OK):

{
  "success": true,
  "message": "Bid request deleted successfully"
}

Error Responses:

403 Forbidden: Cannot delete request after bidding started or bid accepted
404 Not Found: Bid request not found

Accept Bid

Endpoint: POST {{url}}/patients/{patient_id}/procedure_bid_requests/{id}/accept_bid?bid_id={bid_id}

Description: Accept a specific bid for a procedure request. This closes the request and marks the selected bid as accepted.

Query Parameters:

Parameter	Type	Required	Description
`bid_id`	Integer	Yes	ID of the bid to accept

Example Request: POST {{url}}/patients/8/procedure_bid_requests/1/accept_bid?bid_id=1

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "status": "accepted",
    "accepted_bid_id": 1,
    "accepted_at": "2025-01-08T15:30:00Z"
  },
  "message": "Bid accepted successfully"
}

Error Responses:

400 Bad Request: Missing or invalid bid_id parameter
401 Unauthorized: Invalid authentication
403 Forbidden: Bid request not open for acceptance
404 Not Found: Bid request or bid not found
422 Unprocessable Entity: Bid does not belong to this request or bid not in pending status

Clinic Bid APIs

Submit Procedure Bid

Endpoint: POST {{url}}/clinics/{clinic_id}/procedure_bids

Description: Submit a bid for a procedure request. Clinics can offer their services, pricing, and timeline.

Request Body:

{
  "procedure_bid_request_id": 1,
  "doctor_id": 1,
  "offered_price": 12000,
  "currency": "INR",
  "proposed_timeline": "Procedure can be scheduled within 2 weeks of confirmation. Complete recovery expected in 4-6 weeks.",
  "notes": "Experienced orthopaedic surgeon with 15+ years of practice. State-of-the-art facility with dedicated rehabilitation center. Post-operative care included."
}

Parameters:

Parameter	Type	Required	Description
`procedure_bid_request_id`	Integer	Yes	ID of the bid request to respond to
`doctor_id`	Integer	Yes	Doctor who will perform the procedure
`offered_price`	Integer	Yes	Total price for the procedure
`currency`	String	Yes	Currency code (ISO 4217)
`proposed_timeline`	Text	Yes	Detailed timeline for the procedure
`notes`	Text	No	Additional information about the offer

Response (201 Created):

{
  "success": true,
  "data": {
    "id": 1,
    "procedure_bid_request_id": 1,
    "clinic_id": 3,
    "doctor_id": 1,
    "offered_price": 12000,
    "currency": "INR",
    "proposed_timeline": "Procedure can be scheduled within 2 weeks of confirmation",
    "status": "pending",
    "notes": "Experienced orthopaedic surgeon with 15+ years of practice",
    "created_at": "2025-01-08T11:00:00Z",
    "clinic": {
      "id": 3,
      "name": "City Orthopaedic Centre",
      "city": "Mumbai",
      "rating": 4.7
    },
    "doctor": {
      "id": 1,
      "name": "Dr. Rajesh Kumar",
      "speciality": "Orthopaedic Surgery",
      "rating": 4.8,
      "experience": 15
    }
  },
  "message": "Bid submitted successfully"
}

Error Responses:

400 Bad Request: Invalid parameters
401 Unauthorized: Invalid authentication
403 Forbidden: Doctor not authorized for this clinic
404 Not Found: Bid request, doctor, or clinic not found
422 Unprocessable Entity: Bid request not open or expired

Update Procedure Bid

Endpoint: PUT {{url}}/clinics/{clinic_id}/procedure_bids/{id}

Description: Update an existing bid. Only bids with "pending" status can be updated.

Request Body:

{
  "doctor_id": 1,
  "offered_price": 11000,
  "currency": "INR",
  "proposed_timeline": "Procedure can be scheduled within 1 week of confirmation. Updated pricing includes special discount.",
  "notes": "Special introductory offer. Experienced orthopaedic surgeon with 15+ years of practice. State-of-the-art facility with dedicated rehabilitation center.",
  "status": "pending"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "offered_price": 11000,
    "proposed_timeline": "Procedure can be scheduled within 1 week of confirmation",
    "status": "pending",
    "updated_at": "2025-01-08T12:00:00Z"
  },
  "message": "Bid updated successfully"
}

List Clinic Bids

Endpoint: GET {{url}}/clinics/{clinic_id}/procedure_bids

Description: Retrieve all bids submitted by a clinic with optional filtering and pagination.

Query Parameters:

page: Page number (default: 1)
per_page: Items per page (default: 20, max: 100)
status: Filter by status ("pending", "accepted", "withdrawn", "rejected")
doctor_id: Filter by specific doctor

Example Request: GET {{url}}/clinics/3/procedure_bids?page=1&per_page=10&status=pending

Response (200 OK):

{
  "success": true,
  "data": {
    "procedure_bids": [
      {
        "id": 1,
        "procedure_bid_request_id": 1,
        "doctor_id": 1,
        "offered_price": 11000,
        "currency": "INR",
        "status": "pending",
        "created_at": "2025-01-08T11:00:00Z",
        "procedure_bid_request": {
          "id": 1,
          "urgency_level": "urgent",
          "bid_deadline": "2025-01-10T18:00:00Z",
          "basic_procedure": {
            "name": "Arthroscopic Knee Surgery"
          }
        },
        "doctor": {
          "id": 1,
          "name": "Dr. Rajesh Kumar",
          "speciality": "Orthopaedic Surgery"
        }
      }
    ],
    "total_pages": 1,
    "total_records": 1,
    "current_page": 1
  }
}

Get Bid Details

Endpoint: GET {{url}}/clinics/{clinic_id}/procedure_bids/{id}

Description: Retrieve detailed information about a specific bid including the associated bid request.

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "procedure_bid_request_id": 1,
    "clinic_id": 3,
    "doctor_id": 1,
    "offered_price": 11000,
    "currency": "INR",
    "proposed_timeline": "Procedure can be scheduled within 1 week of confirmation",
    "status": "pending",
    "notes": "Special introductory offer with comprehensive post-operative care",
    "created_at": "2025-01-08T11:00:00Z",
    "updated_at": "2025-01-08T12:00:00Z",
    "procedure_bid_request": {
      "id": 1,
      "patient_id": 8,
      "urgency_level": "urgent",
      "status": "open",
      "preferred_timestamp": "2025-01-15T10:00:00Z",
      "bid_deadline": "2025-01-10T18:00:00Z",
      "min_budget": 5000,
      "max_budget": 15000,
      "additional_requirements": "Looking for a clinic with post-operative rehabilitation facilities",
      "basic_procedure": {
        "id": 8,
        "name": "Arthroscopic Knee Surgery",
        "category_name": "Orthopaedic Surgery"
      }
    },
    "clinic": {
      "id": 3,
      "name": "City Orthopaedic Centre",
      "city": "Mumbai",
      "rating": 4.7
    },
    "doctor": {
      "id": 1,
      "name": "Dr. Rajesh Kumar",
      "speciality": "Orthopaedic Surgery",
      "rating": 4.8,
      "experience": 15
    }
  }
}

Delete Procedure Bid

Endpoint: DELETE {{url}}/clinics/{clinic_id}/procedure_bids/{id}

Description: Delete a procedure bid. Only bids with "pending" status can be deleted. Accepted bids cannot be deleted.

Response (200 OK):

{
  "success": true,
  "message": "Bid deleted successfully"
}

Error Responses:

401 Unauthorized: Invalid authentication
403 Forbidden: Cannot delete bid after acceptance
404 Not Found: Bid not found or does not belong to this clinic

Bid Status Values

Bid Request Status

open: Accepting bids
closed: No longer accepting bids (deadline passed)
accepted: Bid has been accepted
expired: Bid deadline passed without acceptance

Bid Status

pending: Bid submitted, awaiting decision
accepted: Bid has been accepted by patient
withdrawn: Bid withdrawn by clinic
rejected: Bid rejected by patient

Error Response Format

All error responses follow this format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameters provided",
    "details": {
      "field": "offered_price",
      "error": "must be greater than 0"
    }
  }
}

Rate Limiting

API endpoints are rate-limited to prevent abuse:

Create/Update operations: 10 requests per minute
List/Retrieve operations: 100 requests per minute

Webhooks

Clinics can configure webhooks to receive notifications about:

New bid requests matching their specialties
Bid acceptance/rejection
Bid request status changes

Configure webhooks through clinic settings or API endpoints.

Procedure Bid APIs

OverviewCopy Anchor Link

AuthenticationCopy Anchor Link

Patient Bid Request APIsCopy Anchor Link

Create Procedure Bid RequestCopy Anchor Link

Update Procedure Bid RequestCopy Anchor Link

List Patient Bid RequestsCopy Anchor Link

Get Bid Request DetailsCopy Anchor Link

Delete Bid RequestCopy Anchor Link

Accept BidCopy Anchor Link

Clinic Bid APIsCopy Anchor Link

Submit Procedure BidCopy Anchor Link

Update Procedure BidCopy Anchor Link

List Clinic BidsCopy Anchor Link

Get Bid DetailsCopy Anchor Link

Delete Procedure BidCopy Anchor Link

Bid Status ValuesCopy Anchor Link

Bid Request StatusCopy Anchor Link

Bid StatusCopy Anchor Link

Error Response FormatCopy Anchor Link

Rate LimitingCopy Anchor Link

WebhooksCopy Anchor Link

On this page

Overview

Authentication

Patient Bid Request APIs

Create Procedure Bid Request

Update Procedure Bid Request

List Patient Bid Requests

Get Bid Request Details

Delete Bid Request

Accept Bid

Clinic Bid APIs

Submit Procedure Bid

Update Procedure Bid

List Clinic Bids

Get Bid Details

Delete Procedure Bid

Bid Status Values

Bid Request Status

Bid Status

Error Response Format

Rate Limiting

Webhooks