{"openapi":"3.1.0","info":{"title":"Housecall Pro (BYOK) API","version":"0.1.0","description":"Housecall Pro (BYOK) lets an AI assistant read your own Housecall Pro data through the Housecall Pro API with a key you supply (Housecall Pro API key (needs a plan that includes API access)). Read-only: 10 tools (get_company, list_jobs, get_job, list_job_appointments, list_estimates, list_invoices, list_leads, list_customers, list_employees, list_job_types). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-housecallpro.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-housecallpro/docs"},"termsOfService":"https://connectorbay.com/byok-housecallpro/terms"},"servers":[{"url":"https://byok-housecallpro.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-housecallpro/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_company":{"post":{"operationId":"get_company","summary":"Show the company behind the key: name, website, phone, time zone and address. Use for \"Which company is my Housecall Pro","description":"Show the company behind the key: name, website, phone, time zone and address. Use for \"Which company is my Housecall Pro key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_companyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_jobs":{"post":{"operationId":"list_jobs","summary":"List jobs with invoice number, description, work status, customer name, city, schedule, totals in cents and tags; filter","description":"List jobs with invoice number, description, work status, customer name, city, schedule, totals in cents and tags; filter by customer or start time. Use for \"Which Housecall Pro jobs are scheduled this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs of this customer id.","title":"Customer Id"},"scheduled_start_min":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records starting at or after this ISO 8601 date-time, for example 2026-10-19T00:00:00Z.","title":"Scheduled Start Min"},"scheduled_start_max":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records starting at or before this ISO 8601 date-time.","title":"Scheduled Start Max"},"sort_by":{"anyOf":[{"enum":["created_at","updated_at","invoice_number","id","description","work_status"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by created_at (default), updated_at, invoice_number, id, description or work_status.","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default desc).","title":"Sort Direction"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50, default 10).","title":"Page Size"}},"title":"list_jobsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_job":{"post":{"operationId":"get_job","summary":"Get one job by id with description, work status, customer name, city, schedule and totals in cents. Use for \"Show Housec","description":"Get one job by id with description, work status, customer name, city, schedule and totals in cents. Use for \"Show Housecall Pro job job_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Housecall Pro job id, for example job_1 (see list_jobs).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_jobArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_job_appointments":{"post":{"operationId":"list_job_appointments","summary":"List the appointments of one job with date, start and end time, anytime flag and arrival window. Use for \"When are the v","description":"List the appointments of one job with date, start and end time, anytime flag and arrival window. Use for \"When are the visits for job job_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"Job id (see list_jobs).","maxLength":200,"title":"Job Id","type":"string"}},"required":["job_id"],"title":"list_job_appointmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_estimates":{"post":{"operationId":"list_estimates","summary":"List estimates with number, work status, customer name, city and schedule; filter by customer or start time. Use for \"Wh","description":"List estimates with number, work status, customer name, city and schedule; filter by customer or start time. Use for \"Which Housecall Pro estimates are scheduled\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only estimates of this customer id.","title":"Customer Id"},"scheduled_start_min":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records starting at or after this ISO 8601 date-time, for example 2026-10-19T00:00:00Z.","title":"Scheduled Start Min"},"scheduled_start_max":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records starting at or before this ISO 8601 date-time.","title":"Scheduled Start Max"},"sort_by":{"anyOf":[{"enum":["created_at","updated_at","id"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by created_at (default), updated_at or id.","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default desc).","title":"Sort Direction"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50, default 10).","title":"Page Size"}},"title":"list_estimatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices with status, number, amounts in cents, due date, paid date and job id; filter by status or created date. U","description":"List invoices with status, number, amounts in cents, due date, paid date and job id; filter by status or created date. Use for \"Which Housecall Pro invoices are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["open","pending_payment","paid","voided","uncollectible","canceled"],"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices with this status.","title":"Status"},"created_at_min":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices created at or after this ISO 8601 date-time.","title":"Created At Min"},"created_at_max":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices created at or before this ISO 8601 date-time.","title":"Created At Max"},"sort_by":{"anyOf":[{"enum":["amount","created_at","due_amount","due_at","invoice_number","paid_at","sent_at","status","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by created_at (default), amount, due_amount, due_at, invoice_number, paid_at, sent_at, status or updated_at.","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default desc).","title":"Sort Direction"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50, default 10).","title":"Page Size"}},"title":"list_invoicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_leads":{"post":{"operationId":"list_leads","summary":"List leads with number, status, pipeline stage, lead source, tags and total in cents; filter by status or customer. Use ","description":"List leads with number, status, pipeline stage, lead source, tags and total in cents; filter by status or customer. Use for \"Which Housecall Pro leads are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["open","won","lost"],"type":"string"},{"type":"null"}],"default":null,"description":"Only leads with this status.","title":"Status"},"customer_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only leads of this customer id.","title":"Customer Id"},"sort_by":{"anyOf":[{"enum":["created_at","updated_at","id","status"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by created_at (default), updated_at, id or status.","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default desc).","title":"Sort Direction"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50, default 10).","title":"Page Size"}},"title":"list_leadsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_customers":{"post":{"operationId":"list_customers","summary":"List or search customers by name, email, phone or address text; returns names, company, lead source and tags (contact de","description":"List or search customers by name, email, phone or address text; returns names, company, lead source and tags (contact details are left out). Use for \"Find the Housecall Pro customer named Lopez\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against name, email, mobile number and address.","title":"Q"},"sort_by":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Customer attribute to sort by, for example created_at (default).","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default desc).","title":"Sort Direction"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50, default 10).","title":"Page Size"}},"title":"list_customersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_employees":{"post":{"operationId":"list_employees","summary":"List active employees with name, role, tags and colour (contact details and permissions are left out). Use for \"Who are ","description":"List active employees with name, role, tags and colour (contact details and permissions are left out). Use for \"Who are the employees in Housecall Pro\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort_by":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Employee attribute to sort by, for example created_at (default).","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default desc).","title":"Sort Direction"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 50, default 10).","title":"Page Size"}},"title":"list_employeesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_job_types":{"post":{"operationId":"list_job_types","summary":"List the job types defined for the company, optionally filtered by name. Use for \"Which job types does our Housecall Pro","description":"List the job types defined for the company, optionally filtered by name. Use for \"Which job types does our Housecall Pro account use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only job types whose name matches this text.","title":"Name"}},"title":"list_job_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}