The Housecall Pro API, in practice

Everything below was checked against a live Housecall Pro MAX account rather than taken from the documentation. Where the two disagree, this page follows the account. Your account may still differ. Plans, permissions and data-entry habits all change what you see, so treat this as a strong prior, not a promise.

Do you have API access?

API access comes with Housecall Pro's MAX plan. In Housecall Pro open My Apps, click Go to App store, open API Key Management, and generate a key as either Full access or Read-only. You need an admin login to do it. The step by step version is on the MCP page.

That choice is the entire permission boundary. There is no per-endpoint scoping, no scopes list, and no way to grant one route and withhold another. Two consequences catch people out:

• A read-only key returns 401 on every write, with a message about permissions, which reads like a broken route if you only look at the status code.
• Only an admin can generate a key, and admins have full account access, so the key reaches the whole book rather than the slice its creator happens to work in.

There is no self-serve developer dashboard and no app registration. OAuth credentials exist, but they are issued to official integration partners by email rather than through a signup flow, so for almost everyone the API key is the way in.

Connecting: base URL and auth

Two details that reject every request if you get them wrong:

Base URL   https://api.housecallpro.com     (no /v1, a version prefix 404s everything)
Auth       Authorization: Token <your-key>   (Token, not Bearer)

Bearer is the near-universal convention and it is wrong here. If every route returns 401 with a key you just generated, this is almost always why.

Money is integer cents, everywhere

Every money field on every entity, whether jobs, invoices, estimates or line items, is an integer number of cents.

This runs both directions. Send unit_price: 1234 on a write and the job total reads $12.34. So a program that passes a dollar figure straight through bills one hundredth of the intended amount, and a report that reads cents as dollars overstates revenue a hundredfold. Convert once, at the boundary, and state which side of it you are on.

Housecall Pro runs three path namespaces

This is the single most useful undocumented fact about the API, and it is why so many integrations ship phantom "not available" gaps. The same account and the same key reach three different namespaces, each with its own envelope and id style.

A capability missing from one namespace often lives in another. /price_book/services returns 404 while /api/price_book/services returns your whole price book. /job_types is a dead path while /job_fields/job_types works. Job notes look write-only because GET /jobs/{id}/notes 404s, but GET /api/jobs/{id}/notes returns them.

One caveat worth internalising: /api/* is a per-route allowlist, not a second front door. A handful of paths under that prefix answer an API key; most return 401 to any key regardless of scope. Probe the specific route rather than assuming the namespace is open.

Reading the error responses

Housecall Pro returns four shapes that all look like failure and mean very different things. Read the content type as well as the status code. This one table turns guesswork into a single request.

There are also two error envelopes in circulation: some routes return {"errors":{"field":"is missing"}} with a 422, others {"error":{"message":"…"}} with a 400. Parse both.

Filters that are silently ignored

These parameters are accepted without complaint and then ignored. You get the full dataset back and no indication that filtering did not happen, which is worse than an error, because the result looks plausible.

• updated_after, which returns everything
• Invoice date filters, including service_date_min/max, invoice_date_min/max, start_date, end_date all return the complete set
• ?status= on invoices, which returns empty or errors
• customer_id on equipment, plus per_page and limit generally, all silently unfiltered

Filters that do work: work_status[]= (array syntax) and scheduled_start_min / scheduled_start_max on /jobs. page_size=100 is honoured, which is worth setting. The default page size makes a full sweep ten times longer than it needs to be.

The general rule: an ignored parameter does not error. Prove that a filter filters before you trust a number that depends on it.

The work_status vocabulary trap

The input vocabulary and the response vocabulary are different languages.

The string completed never appears in a response. Code that tests work_status == "completed" matches zero rows in a ten-thousand-job book and raises no error. It just reports that nothing was completed. Bucket on the complete prefix, and substring-match on cancel.

Delete semantics, and the revenue-corrupting one

Deletion behaves differently for every entity, and two of them will quietly corrupt totals.

• Deleted jobs still come back from GET /jobs, carrying their full amount. The record gains a deleted_at timestamp and its status flips, but it stays in list responses. Anything counting jobs or summing revenue must filter on deleted_at or deleted work inflates the total.
• pro canceled does not mean "canceled." Deleting a job and canceling a job produce the same status; deleted_at is the only discriminator.
• Deleted customers vanish from lists but stay fetchable by id, returning 200 with the full record and no deleted flag of any kind. If you cache customer ids you cannot tell from the record that one is gone, so re-check membership with a list query.
• Leads delete cleanly. Tags cannot be deleted through the API at all.

Writes that return 200 and change nothing

The most dangerous behaviour on this API. Several writes return 200 OK and change nothing at all. Never trust a 2xx on a write. Read it back, or it did not happen.

• PATCH /jobs/{id} honours only the nested schedule object. Flat scheduled_start keys return 200 and are ignored. So does tags.
• A job's description is derived from its line items, so writing it returns 200 and does nothing, because there is no direct description write.
• PUT /customers/{id} does not replace, it merges, identical to PATCH. A PUT carrying only first_name leaves every other field intact. Good news for safety, surprising if you expected REST semantics.

Structural surprises

• /jobs/{id}/line_items is empty on completed jobs. The reliable record of what was billed is the invoice, which embeds its items[] inline.
• Invoices have no top-level customer_id. Resolve it through the invoice's job_id.
• Invoices have no total_amount. amount is post-discount pre-tax, subtotal is pre-discount pre-tax, and gross-with-tax is amount plus the sum of taxes[].amount.
• Estimate line items are readable, but only at the nested option path. GET /estimates/{id} omits them, which makes them look unreachable. They are returned in full, including multi-line descriptions, at the option's own line items route, which is what makes read-back verification after a write possible.
• Ids are layered. An estimate has a public id and its options have their own; several routes key on the option rather than the estimate.

Rate limits

Real, undocumented, and invisible until they fire. No X-RateLimit-* headers are returned, only a request id. The important nuance is that the limit is sustained-volume, not burst:

So "we ran a quick test and saw no 429s" is not evidence of headroom. Anything longer than a few dozen calls needs retry-with-backoff, and the retries do succeed.

What is genuinely not on the public API

Not "we could not find it". These return an HTML 404, which is the tell that the route does not exist:

• No invoice creation. Invoices can be read, including a rendered document, but not created.
• No customer delete, and addresses are append-only, with no update and no delete.
• No tag delete, ever. Create and rename only. Deleting a tag is a dashboard action, and Housecall Pro warns that it erases the tag from historical records.
• No estimate update or delete, and no option update or delete.
• No top-level appointments collection. Appointments exist only nested under a job, where they have full CRUD.
• No price-book service creation. Materials, categories and price forms are fully writable; services are read-only, which is why an audit of your services can produce a worklist but cannot fix them for you.
• Service plans, recurring service plans, and equipment / Property Profile data are not on the public API in any namespace.
• Webhooks are partner-gated. There is no list route, and creating a subscription with an ordinary MAX key fails because it wants a registered partner app. See the webhooks page.

Full route-by-route detail, including what each write demands of you, is on the endpoint reference.

Common questions