{"openapi":"3.0.3","info":{"title":"3Bids Workflow API","description":"API for triggering 3Bids platform event workflows.\n\nThese webhooks are called by the 3Bids Python backend when platform events occur. Each event triggers an **inline n8n workflow** on _n8n Cloud_ platform that sends emails directly via _SendGrid_.\n\nThe system is designed to be as efficient as possible to keep execution costs to a minimum. In order to accomplish this, there is duplication of code on every workflow, most notably the HTML layout markup. These duplicate nodes are synchronized with each other by external tooling.\n\n_Note: upgrading the n8n Cloud subscription to the Pro tier would grant us the ability to utilize global environment variables to DRY out this duplication._\n\n## Architecture\n___\n\n**Option 1: Direct Webhooks (Recommended)**\nCall event-specific endpoints directly for lowest latency and execution cost.\n\n*Execution cost*: **one (1)** workflow execution per event.\n\n```\nPython Backend → /webhook/<event-name> → Inline Workflow → SendGrid\n```\n\n**Option 2: Event Router**\nSend all events to a single endpoint with `event_type` field for routing.\n\n*Execution cost*: **two (2)** workflow executions per event (one for the router workflow and one for the event workflow).\n\n```\nPython Backend → /webhook/event-router → Route by event_type → Inline Workflow\n```\n\n## Payload Formats\n___\n\nBoth **nested** and **flat** formats are supported:\n\n```json\n// Nested format (preferred)\n{\n  \"event_type\": \"bid_accepted\",\n  \"job\": { \"job_number\": 2172, \"title\": \"Fix faucet\", \"city\": \"Austin\" },\n  \"contractor\": { \"id\": 2282, \"name\": \"John\", \"email\": \"john@example.com\" }\n}\n\n// Flat format (fallback)\n{\n  \"event_type\": \"bid_accepted\",\n  \"job_number\": 2172,\n  \"job_title\": \"Fix faucet\",\n  \"city\": \"Austin\",\n  \"contractor_id\": 2282,\n  \"contractor_name\": \"John\",\n  \"contractor_email\": \"john@example.com\"\n}\n```\n\n## Rate Limits\n___\n\n- **job_posted**: 10 requests/minute (contractor discovery is expensive)\n- **Other events**: 60 requests/minute\n- Burst: Up to 5 concurrent requests\n\n## Testing\n___\n\nUse the test webhook URLs (replace `/webhook/` with `/webhook-test/`) for development:\n```\nProduction: /webhook/job-posted\nTest:       /webhook-test/job-posted\n```\n","version":"2.1.0","contact":{"name":"3Bids Engineering","email":"engineering@3bids.io","url":"https://3bids.io"},"license":{"name":"Proprietary","url":"https://3bids.io/terms"}},"servers":[{"url":"https://snowday555.app.n8n.cloud","description":"Production n8n instance"},{"url":"http://localhost:5678","description":"Local development"}],"tags":[{"name":"Router","description":"Universal event router endpoint"},{"name":"Job Lifecycle","description":"Events related to job posting and completion"},{"name":"Bidding","description":"Events related to contractor bids"},{"name":"Payment","description":"Events related to escrow and payments"},{"name":"Onboarding","description":"User onboarding events"},{"name":"Change Orders","description":"Change order events"},{"name":"Disputes","description":"Dispute-related events"},{"name":"Reviews","description":"Review and feedback events"}],"paths":{"/webhook/event-router":{"post":{"operationId":"eventRouter","summary":"Universal Event Router","description":"Routes events to the appropriate workflow based on `event_type` field.\n\nUse this endpoint when you want a single integration point for all events.\nThe router adds 1 additional execution but simplifies backend integration.\n\n**Supported event_type values:**\n- `poster_onboarding`, `contractor_onboarding`\n- `job_posted`, `job_completed`, `job_cancelled`\n- `bid_submitted`, `bid_accepted`, `bid_rejected`, `bid_withdrawn`\n- `escrow_funded`, `in_home_lead_purchased`\n- `change_order_requested`, `change_order_approved`, `change_order_rejected`\n- `dispute_opened`\n- `review_reminder_start`\n\n**Execution Cost**: 2 workflow executions (router + event workflow)\n","tags":["Router"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterEventRequest"},"examples":{"bid_accepted":{"summary":"Route a bid_accepted event","value":{"event_type":"bid_accepted","job":{"job_number":2172,"title":"Fix leaky faucet","city":"Austin","state":"TX"},"contractor":{"id":2282,"name":"John's Plumbing","email":"john@example.com"},"poster":{"id":2286,"name":"Jane Smith","email":"jane@example.com"},"bid":{"id":186,"amount":500}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/job-posted":{"post":{"operationId":"jobPosted","summary":"Job Posted Event","description":"Triggered when a homeowner posts a new job on the platform.\n\nThis inline workflow:\n1. Receives the job data with pre-discovered contractors array\n2. Validates required fields\n3. Loops through contractors internally\n4. Renders and sends email to each contractor via SendGrid API\n\n**Execution Cost**: 1 workflow execution (loops internally over N contractors)\n\nNote: Contractor discovery via Google Places API happens in a separate workflow\nbefore this event is triggered.\n","tags":["Job Lifecycle"],"x-rateLimit":{"limit":10,"period":"minute","burst":5},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPostedRequest"},"examples":{"kitchen_job":{"summary":"Kitchen remodel job","value":{"job_number":2174,"poster_id":2290,"city":"Avon","state":"OH","job_type_id":"012006","job_type_name":"Kitchen Appliance Installation","subcategory_name":"Kitchen","category_id":"01","property_id":932,"job_title":"Kitchen faucet replacement","latitude":41.4691286,"longitude":-81.9817594}},"plumbing_job":{"summary":"Plumbing job in Austin","value":{"job_number":2176,"poster_id":2290,"city":"Austin","state":"TX","job_type_id":"012006","job_type_name":"Plumbing","subcategory_name":"Plumbing","category_id":"01","property_id":933,"job_title":"Fix leaky faucet","latitude":30.2672,"longitude":-97.7431}}}}}},"responses":{"200":{"description":"Workflow started successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowStartedResponse"},"example":{"message":"Workflow was started"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Missing required field: job_number"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Rate limit exceeded. Try again in 60 seconds."}}}},"500":{"description":"Workflow execution error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Workflow execution failed"}}}}}}},"/webhook/bid-submitted":{"post":{"operationId":"bidSubmitted","summary":"Bid Submitted Event","description":"Triggered when a contractor submits a bid on a job.\n\nSends notification email to the homeowner (poster).\n\n**Execution Cost**: 1 workflow execution\n","tags":["Bidding"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidEventRequest"},"example":{"event_type":"bid_submitted","bid":{"id":186,"amount":500},"job":{"number":2172,"type":"Plumbing","city":"Austin","state":"TX"},"contractor":{"id":2282,"name":"John's Plumbing","company":"John's Plumbing LLC","email":"john@example.com","phone":"(512) 555-1234"},"poster":{"id":2286,"name":"Jane Smith","email":"jane@example.com"}}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/bid-accepted":{"post":{"operationId":"bidAccepted","summary":"Bid Accepted Event","description":"Triggered when a homeowner accepts a contractor's bid.\n\nSends notification email to the contractor.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Bidding"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidEventRequest"},"example":{"event_type":"bid_accepted","bid":{"id":186,"amount":500},"job":{"number":2172,"type":"Plumbing","city":"Austin","state":"TX"},"contractor":{"id":2282,"name":"John's Plumbing","email":"john@example.com"},"poster":{"id":2286,"name":"Jane Smith","email":"jane@example.com"}}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/bid-rejected":{"post":{"operationId":"bidRejected","summary":"Bid Rejected Event","description":"Triggered when a homeowner rejects a contractor's bid.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Bidding"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/bid-withdrawn":{"post":{"operationId":"bidWithdrawn","summary":"Bid Withdrawn Event","description":"Triggered when a contractor withdraws their bid.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Bidding"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/escrow-funded":{"post":{"operationId":"escrowFunded","summary":"Escrow Funded Event","description":"Triggered when a homeowner funds the escrow for an accepted bid.\n\nNotifies the contractor that they can begin work.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Payment"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentEventRequest"},"example":{"event_type":"escrow_funded","escrow":{"id":456,"amount":500},"job":{"number":2172,"title":"Fix leaky faucet"},"contractor":{"id":2282,"name":"John's Plumbing","email":"john@example.com"},"poster":{"id":2286,"name":"Jane Smith","email":"jane@example.com"}}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/in-home-lead-purchased":{"post":{"operationId":"inHomeLeadPurchased","summary":"In-Home Lead Purchased Event","description":"Triggered when a contractor purchases an in-home lead.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Payment"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/job-completed":{"post":{"operationId":"jobCompleted","summary":"Job Completed Event","description":"Triggered when a job is marked as completed.\n\nSends completion notification to the contractor.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Job Lifecycle"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCompletionEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/job-cancelled":{"post":{"operationId":"jobCancelled","summary":"Job Cancelled Event","description":"Triggered when a job is cancelled.\n\nSends notification emails to both poster and contractor (parallel branches).\n\n**Execution Cost**: 1 workflow execution\n","tags":["Job Lifecycle"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCompletionEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/poster-onboarding":{"post":{"operationId":"posterOnboarding","summary":"Poster Onboarding Event","description":"Triggered when a new homeowner completes registration.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Onboarding"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/contractor-onboarding":{"post":{"operationId":"contractorOnboarding","summary":"Contractor Onboarding Event","description":"Triggered when a new contractor completes registration.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Onboarding"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/change-order-requested":{"post":{"operationId":"changeOrderRequested","summary":"Change Order Requested Event","description":"Triggered when a change order is requested.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Change Orders"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeOrderEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/change-order-approved":{"post":{"operationId":"changeOrderApproved","summary":"Change Order Approved Event","description":"Triggered when a change order is approved.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Change Orders"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeOrderEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/change-order-rejected":{"post":{"operationId":"changeOrderRejected","summary":"Change Order Rejected Event","description":"Triggered when a change order is rejected.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Change Orders"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeOrderEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/dispute-opened":{"post":{"operationId":"disputeOpened","summary":"Dispute Opened Event","description":"Triggered when a dispute is opened on a job.\n\nSends notification emails to both poster and contractor (parallel branches).\n\n**Execution Cost**: 1 workflow execution\n","tags":["Disputes"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeEventRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/webhook/review-reminder":{"post":{"operationId":"reviewReminder","summary":"Review Reminder Event","description":"Triggered to remind a poster to leave a review for a contractor after job completion.\n\nSends a friendly reminder email to the poster with a link to leave a review.\n\n**Execution Cost**: 1 workflow execution\n","tags":["Reviews"],"x-rateLimit":{"limit":60,"period":"minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewReminderEventRequest"},"example":{"event_type":"review_reminder_start","job":{"number":2172,"title":"Fix leaky faucet"},"contractor":{"id":2282,"name":"John's Plumbing"},"poster":{"id":2286,"name":"Jane Smith","email":"jane@example.com"}}}}},"responses":{"200":{"$ref":"#/components/responses/WorkflowStarted"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"schemas":{"RouterEventRequest":{"type":"object","description":"Generic event payload for the event router.\nThe `event_type` field determines which workflow handles the event.\nSupports both nested and flat payload formats.\n","required":["event_type"],"properties":{"event_type":{"type":"string","description":"Event type for routing","enum":["poster_onboarding","contractor_onboarding","job_posted","bid_submitted","bid_accepted","bid_rejected","bid_withdrawn","escrow_funded","in_home_lead_purchased","change_order_requested","change_order_approved","change_order_rejected","dispute_opened","job_completed","job_cancelled","review_reminder_start"],"example":"bid_accepted"},"source":{"type":"string","default":"3bids.io"},"timestamp":{"type":"string","format":"date-time"},"job":{"$ref":"#/components/schemas/Job"},"contractor":{"$ref":"#/components/schemas/Contractor"},"poster":{"$ref":"#/components/schemas/Poster"},"bid":{"$ref":"#/components/schemas/Bid"},"job_number":{"type":"integer","description":"Flat format alternative to job.job_number"},"job_title":{"type":"string","description":"Flat format: job.title"},"contractor_id":{"type":"integer","description":"Flat format: contractor.id"},"contractor_email":{"type":"string","description":"Flat format: contractor.email"},"poster_id":{"type":"integer","description":"Flat format: poster.id"},"poster_email":{"type":"string","description":"Flat format: poster.email"}}},"JobPostedRequest":{"type":"object","required":["job_number","poster_id","city","state","job_type_name","subcategory_name","job_title","latitude","longitude"],"properties":{"job_number":{"type":"integer","description":"Unique job identifier","example":2174},"poster_id":{"type":"integer","description":"Homeowner's user ID","example":2290},"city":{"type":"string","description":"Job location city","example":"Austin"},"state":{"type":"string","description":"Job location state (2-letter code)","example":"TX","minLength":2,"maxLength":2},"job_type_id":{"type":"string","description":"Job type category ID","example":"012006"},"job_type_name":{"type":"string","description":"Human-readable job type","example":"Plumbing"},"subcategory_name":{"type":"string","description":"Job subcategory for contractor search","example":"Plumbing"},"category_id":{"type":"string","description":"Top-level category ID","example":"01"},"property_id":{"type":"integer","description":"Property ID where job is located","example":932},"job_title":{"type":"string","description":"User-provided job title","example":"Fix leaky faucet"},"latitude":{"type":"number","format":"double","description":"Job location latitude","example":30.2672},"longitude":{"type":"number","format":"double","description":"Job location longitude","example":-97.7431},"budget_low":{"type":"number","description":"Minimum budget (optional)","example":100},"budget_high":{"type":"number","description":"Maximum budget (optional)","example":500}}},"BidEventRequest":{"type":"object","description":"Payload for bid-related events. Supports both nested and flat formats.\n","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["bid_submitted","bid_accepted","bid_rejected","bid_withdrawn"],"example":"bid_accepted"},"source":{"type":"string","default":"3bids.io"},"timestamp":{"type":"string","format":"date-time"},"bid":{"$ref":"#/components/schemas/Bid"},"job":{"$ref":"#/components/schemas/Job"},"contractor":{"$ref":"#/components/schemas/Contractor"},"poster":{"$ref":"#/components/schemas/Poster"},"bid_id":{"type":"integer","description":"Flat format: bid.id"},"bid_amount":{"type":"number","description":"Flat format: bid.amount"},"job_number":{"type":"integer","description":"Flat format alternative to job.job_number"},"job_title":{"type":"string","description":"Flat format: job.title"},"city":{"type":"string","description":"Flat format: job.city"},"state":{"type":"string","description":"Flat format: job.state"},"contractor_id":{"type":"integer","description":"Flat format: contractor.id"},"contractor_name":{"type":"string","description":"Flat format: contractor.name"},"contractor_email":{"type":"string","description":"Flat format: contractor.email"},"poster_id":{"type":"integer","description":"Flat format: poster.id"},"poster_name":{"type":"string","description":"Flat format: poster.name"},"poster_email":{"type":"string","description":"Flat format: poster.email"}}},"PaymentEventRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["escrow_funded","in_home_lead_purchased"],"example":"escrow_funded"},"escrow":{"$ref":"#/components/schemas/Escrow"},"job":{"$ref":"#/components/schemas/Job"},"contractor":{"$ref":"#/components/schemas/Contractor"},"poster":{"$ref":"#/components/schemas/Poster"},"escrow_id":{"type":"integer"},"escrow_amount":{"type":"number"},"job_number":{"type":"integer"},"contractor_id":{"type":"integer"},"contractor_email":{"type":"string"},"poster_id":{"type":"integer"},"poster_email":{"type":"string"}}},"JobCompletionEventRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["job_completed","job_cancelled"],"example":"job_completed"},"job":{"$ref":"#/components/schemas/Job"},"contractor":{"$ref":"#/components/schemas/Contractor"},"poster":{"$ref":"#/components/schemas/Poster"},"job_number":{"type":"integer"},"job_title":{"type":"string"},"contractor_id":{"type":"integer"},"contractor_email":{"type":"string"},"poster_id":{"type":"integer"},"poster_email":{"type":"string"}}},"OnboardingEventRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["poster_onboarding","contractor_onboarding"],"example":"poster_onboarding"},"user":{"$ref":"#/components/schemas/User"},"user_id":{"type":"integer"},"user_name":{"type":"string"},"user_email":{"type":"string"},"user_type":{"type":"string"}}},"ChangeOrderEventRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["change_order_requested","change_order_approved","change_order_rejected"],"example":"change_order_requested"},"change_order":{"$ref":"#/components/schemas/ChangeOrder"},"job":{"$ref":"#/components/schemas/Job"},"contractor":{"$ref":"#/components/schemas/Contractor"},"poster":{"$ref":"#/components/schemas/Poster"},"change_order_id":{"type":"integer"},"change_order_amount":{"type":"number"},"job_number":{"type":"integer"},"contractor_id":{"type":"integer"},"contractor_email":{"type":"string"},"poster_id":{"type":"integer"},"poster_email":{"type":"string"}}},"DisputeEventRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["dispute_opened"],"example":"dispute_opened"},"dispute":{"$ref":"#/components/schemas/Dispute"},"job":{"$ref":"#/components/schemas/Job"},"contractor":{"$ref":"#/components/schemas/Contractor"},"poster":{"$ref":"#/components/schemas/Poster"},"dispute_id":{"type":"integer"},"dispute_reason":{"type":"string"},"job_number":{"type":"integer"},"contractor_id":{"type":"integer"},"contractor_email":{"type":"string"},"poster_id":{"type":"integer"},"poster_email":{"type":"string"}}},"ReviewReminderEventRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["review_reminder_start"],"example":"review_reminder_start"},"job":{"$ref":"#/components/schemas/Job"},"contractor":{"$ref":"#/components/schemas/Contractor"},"poster":{"$ref":"#/components/schemas/Poster"},"job_number":{"type":"integer"},"job_title":{"type":"string"},"contractor_id":{"type":"integer"},"contractor_name":{"type":"string"},"poster_id":{"type":"integer"},"poster_name":{"type":"string"},"poster_email":{"type":"string"}}},"Bid":{"type":"object","description":"Bid information (nested format uses short property names)","properties":{"id":{"type":"integer","description":"Unique bid identifier","example":186},"amount":{"type":"number","description":"Bid amount in dollars","example":500},"message":{"type":"string","description":"Optional message from contractor"}}},"Job":{"type":"object","description":"Job information for nested payloads","properties":{"job_number":{"type":"integer","description":"Unique job number","example":2172},"title":{"type":"string","description":"Job title","example":"Fix leaky faucet"},"type":{"type":"string","description":"Job type/category","example":"Plumbing"},"city":{"type":"string","example":"Austin"},"state":{"type":"string","example":"TX"}}},"Contractor":{"type":"object","description":"Contractor information (nested format uses short property names)","properties":{"id":{"type":"integer","example":2282},"name":{"type":"string","example":"John's Plumbing"},"company":{"type":"string","example":"John's Plumbing LLC"},"email":{"type":"string","format":"email","example":"john@example.com"},"phone":{"type":"string","example":"(512) 555-1234"}}},"Poster":{"type":"object","description":"Poster/homeowner information (nested format uses short property names)","properties":{"id":{"type":"integer","example":2286},"name":{"type":"string","example":"Jane Smith"},"email":{"type":"string","format":"email","example":"jane@example.com"},"phone":{"type":"string","nullable":true,"example":null}}},"User":{"type":"object","properties":{"id":{"type":"integer","example":2290},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","format":"email","example":"john@example.com"},"phone":{"type":"string","example":"(512) 555-1234"},"type":{"type":"string","enum":["poster","contractor"],"example":"poster"}}},"Escrow":{"type":"object","properties":{"id":{"type":"integer","example":456},"amount":{"type":"number","example":500},"funded_at":{"type":"string","format":"date-time"}}},"ChangeOrder":{"type":"object","properties":{"id":{"type":"integer","example":789},"description":{"type":"string","example":"Additional work for bathroom fixtures"},"amount":{"type":"number","example":150},"requested_by":{"type":"string","enum":["contractor","poster"]}}},"Dispute":{"type":"object","properties":{"id":{"type":"integer","example":101},"reason":{"type":"string","example":"Work not completed as described"},"opened_by":{"type":"string","enum":["contractor","poster"]}}},"WorkflowStartedResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Email sent"},"event":{"type":"string","example":"bid_accepted"},"statusCode":{"type":"integer","example":202}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message","example":"Missing required field: job_number"},"code":{"type":"string","description":"Error code (optional)","example":"VALIDATION_ERROR"},"details":{"type":"object","description":"Additional error details","additionalProperties":true}}}},"responses":{"WorkflowStarted":{"description":"Workflow started successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowStartedResponse"}}}},"BadRequest":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Validation failed","code":"VALIDATION_ERROR"}}}},"ServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Workflow execution failed","code":"EXECUTION_ERROR"}}}}}},"externalDocs":{"description":"Full 3Bids Documentation","url":"https://github.com/3bids/docs"}}