One contractor's details and history

maintenance.contractor.get

GET/api/v1/households/{household_id}/queries/maintenance.contractor.get

Query
Rigel runs it

One contractor with their contact details and people, recent visits, projects, quotes and invoices, ongoing services, the maintenance tasks they handle and their recent mail (up to 5 email conversations that involve the contractor or any of their people).

Parameters#

One contractor's details and history: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`contractor_id`querystringrequired	A contractor ID, such as ctr_01JC0000000000000000000000.

Response#

200 The answer.

One contractor's details and history: response fields
Field	Description
`id`stringrequired	A contractor ID, such as ctr_01JC0000000000000000000000.
`address`string or nullrequired	The web route that opens it.
`name`stringrequired	The business's name.
`trade`string or nullrequired	What they do.
`phone`string or nullrequired	Their phone number.
`email`string or nullrequired	Their email address.
`website`string or nullrequired	Their website.
`postal_address`string or nullrequired	Their address.
`service_area`string or nullrequired	Where they work.
`notes`string or nullrequired	Notes, as written.
`is_preferred`booleanrequired	Whether the household prefers them.
`contacts`array of objectsrequired
`contacts[].id`stringrequired	A contractor contact ID, such as ccn_01JC0000000000000000000000.
`contacts[].name`stringrequired	The person's name.
`contacts[].role`string or nullrequired	Their role.
`contacts[].phone`string or nullrequired	Their phone number.
`contacts[].email`string or nullrequired	Their email address.
`contacts[].notes`string or nullrequired	Notes, as written.
`visits`array of objectsrequired	Their visits, newest first, at most 20.
`visits[].id`stringrequired	A visit ID, such as vst_01JC0000000000000000000000.
`visits[].address`string or nullrequired	The web route that opens it.
`visits[].title`stringrequired	What it is for.
`visits[].status`one of: scheduled, done, cancelledrequired	Where the visit stands.
`visits[].starts_at`string (date-time) or nullrequired	When they are due, start of the window.
`visits[].ends_at`string (date-time) or nullrequired	End of the arrival window.
`visits[].visited_on`string or nullrequired	When the work happened, YYYY-MM-DD.
`visits[].summary`string or nullrequired	What was done.
`projects`array of objectsrequired	Projects their visits or papers belong to.
`projects[].id`stringrequired	A maintenance project ID, such as mpj_01JC0000000000000000000000.
`projects[].address`string or nullrequired	The web route that opens it.
`projects[].title`stringrequired	What the project is.
`projects[].status`one of: planning, active, on_hold, done, cancelledrequired	planning, active, on_hold, done or cancelled.
`invoices`array of objectsrequired	Their quotes and invoices, newest first.
`invoices[].id`stringrequired	A invoice ID, such as ivc_01JC0000000000000000000000.
`invoices[].kind`one of: quote, invoicerequired	A quote or an invoice.
`invoices[].number`string or nullrequired	The number on the paper.
`invoices[].issued_on`string or nullrequired	The date on it.
`invoices[].currency`stringrequired	An ISO 4217 currency code, such as USD. pattern ^[A-Z]{3}$
`invoices[].total`integer or nullrequired	Its total in minor units.
`invoices[].project_id`string or nullrequired	The project it belongs to.
`invoices[].file_id`string or nullrequired	The original paper.
`services`array of objectsrequired
`services[].id`stringrequired	A ongoing service ID, such as osv_01JC0000000000000000000000.
`services[].name`stringrequired	The service's name.
`services[].scope`string or nullrequired	What they do.
`services[].cadence`string or nullrequired	How often.
`services[].price`integer or nullrequired	The price in minor units.
`services[].currency`string or nullrequired	The price's currency. pattern ^[A-Z]{3}$
`services[].price_per`string or nullrequired	What the price is for.
`services[].status`one of: active, endedrequired	Whether it is still going.
`services[].renews_on`string or nullrequired	When it renews.
`tasks`array of objectsrequired	Maintenance tasks they handle.
`tasks[].id`stringrequired	The task's ID (mtk_…).
`tasks[].address`string or nullrequired	The web route that opens the task, when it has one.
`tasks[].title`stringrequired	The task's title.
`tasks[].importance`one of: essential, recommended, optionalrequired	How much it matters.
`tasks[].status`one of: active, offrequired	Whether the task is on or turned off.
`tasks[].next_due_on`string or nullrequired	When it is next due, YYYY-MM-DD, or null (a usage task with no date).
`tasks[].due_group`one of: overdue, due_soon, this_season, later, null or nullrequired	Overdue, due_soon (within 2 weeks), this_season or later; null for optional and turned-off tasks.
`tasks[].due_in_words`string or nullrequired	"Due in 5 days", "Overdue since Oct 3", "Open until Nov 15" or "Check"; null when off.
`tasks[].asset_id`string or nullrequired	A asset ID, such as ast_01JC0000000000000000000000.
`tasks[].asset_name`string or nullrequired	No description.
`mail`array of objectsrequired	Up to 5 email conversations that involve the contractor or any of their people, newest first.
`mail[].thread_id`stringrequired	A email thread ID, such as emt_01JC0000000000000000000000.
`mail[].address`string or nullrequired	The web route that opens the conversation.
`mail[].subject`stringrequired	The conversation's subject.
`mail[].last_message_at`string (date-time)required	When its newest message was sent.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

One contractor's details and history: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Open a contractor

Their people, visits, quotes, services and recent mail.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.contractor.get?contractor_id=ctr_01M6V9CSWEFJH8CRZCXNAH8109' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.contractor.get?contractor_id=ctr_01M6V9CSWEFJH8CRZCXNAH8109", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.contractor.get?contractor_id=ctr_01M6V9CSWEFJH8CRZCXNAH8109 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CT1JYQHTVTXN1WGZFCJZ

{
  "id": "ctr_01M6V9CSWEFJH8CRZCXNAH8109",
  "address": "/maintenance/people/ctr_01M6V9CSWEFJH8CRZCXNAH8109",
  "name": "Smith Heating & Air",
  "trade": "HVAC",
  "phone": "555-0142",
  "email": "pat@smithhvac.example.com",
  "website": "https://smithhvac.example.com",
  "postal_address": null,
  "service_area": "Within 25 miles of town",
  "notes": "Installed the furnace. Tune-up customers get same-week appointments.",
  "is_preferred": true,
  "contacts": [
    {
      "id": "ccn_01M6V9CSWGTX839J9HJDVKV38M",
      "name": "Pat Smith",
      "role": "Service manager",
      "phone": null,
      "email": null,
      "notes": "Best reached before 10 am."
    }
  ],
  "visits": [
    {
      "id": "vst_01M6V9CSYWPZZCJP1Q0PBTS1SF",
      "address": "/maintenance/visits/vst_01M6V9CSYWPZZCJP1Q0PBTS1SF",
      "title": "Furnace inspection and tune-up",
      "status": "scheduled",
      "starts_at": "2026-11-19T15:00:00.000Z",
      "ends_at": "2026-11-19T17:00:00.000Z",
      "visited_on": null,
      "summary": null
    }
  ],
  "projects": [],
  "invoices": [],
  "services": [
    {
      "id": "osv_01M6V9CSZMV4CA4S1QG2QF9796",
      "name": "Furnace and AC service plan",
      "scope": "One tune-up for the furnace and one for the AC each year, with priority scheduling.",
      "cadence": "Once a year",
      "price": 18900,
      "currency": "USD",
      "price_per": "year",
      "status": "active",
      "renews_on": "2027-09-08"
    }
  ],
  "tasks": [
    {
      "id": "mtk_01M6V9CSWSHKH0MYE1RMRRDC58",
      "address": "/maintenance/tasks/mtk_01M6V9CSWSHKH0MYE1RMRRDC58",
      "title": "Annual furnace inspection",
      "importance": "essential",
      "status": "active",
      "next_due_on": "2026-11-19",
      "due_group": "due_soon",
      "due_in_words": "Due in 12 days",
      "asset_id": "ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
      "asset_name": "Basement furnace"
    }
  ],
  "mail": [
    {
      "thread_id": "emt_01M6V9CSQTWAS9BMMTQ44AST9X",
      "address": "/email/threads/emt_01M6V9CSQTWAS9BMMTQ44AST9X",
      "subject": "Furnace tune-up quote",
      "last_message_at": "2026-11-07T11:17:52.506Z"
    }
  ]
}

For Rigel#

Rigel's tool for this query is maintenance_contractor_get. Rigel runs this on its own, then says what it did. The agent guide has the rest.