Skip to main content

Core Concepts

The Houzz Pro API models the day-to-day work of a home-improvement business: winning new business (leads), running the jobs (projects), and the people, schedules, files, and notes attached to them. This page orients you to that domain model — how the resources relate, how they are scoped, and the conventions that hold across every endpoint — so the individual reference pages read like a map instead of a list.

If you have not made a call yet, start with Getting Started; this page assumes you can already authenticate.

Company scoping​

Every integration authenticates with a service account, and a service account represents exactly one Houzz Pro company. That company is the boundary for everything you do:

  • Every resource you access is automatically scoped to your company. List endpoints return only data belonging to your company.
  • Every resource you create is owned by your company automatically. You never pass a company identifier; it is inferred from your token.
  • IDs are only meaningful within your company. A project ID from one company's data will not resolve against another's.

You can think of the entire API as a view into a single company's workspace. This is why webhook subscriptions, custom field definitions, and reference lists (statuses, types, trades) are all implicitly company-scoped.

The resource graph​

The API is organized around two top-level work objects — the Project and the Lead — plus the people and reference data that support them.

Project — the central work object​

A Project is an active home-improvement job. It is the hub that most other resources hang off of. A project carries:

  • a client — { id, name }, the homeowner or business the work is for
  • a status — { id, name }, its workflow state (see Project Status)
  • a projectType / projectTypeName — its category (see Project Type)
  • one or more addresses — the job-site location(s)
  • budget, notes, owner, archived, and any customFieldEntries

Several resources are sub-resources of a project — you list and create them under the project's path:

Sub-resourcePathWhat it is
Task/v1/projects/{projectId}/tasksActionable to-do items; can link to a milestone
Milestone/v1/projects/{projectId}/milestonesScheduled timeline items; can nest under a parent milestone
Daily Log/v1/daily-logs (with projectId)Timestamped field notes; each log belongs to one project
Punchlist/v1/projects/{projectId}/punchlistThe project's shared checklist of outstanding items
File/v1/files (with contextType=Project)Documents, images, and folders attached to the project

A few relationships worth calling out:

  • Tasks can also belong to a lead (/v1/leads/{leadId}/tasks) or to a punchlist (created by supplying punchlistId). A task may reference a milestoneId.
  • Each project has one punchlist; its items are managed as tasks.
  • Milestones can attach to either a project or a lead, and can nest via parentMilestoneId.

Lead — a potential job​

A Lead (also called an Inquiry — the two names refer to the same object) is a pre-project sales opportunity. Like a project, a lead has a client, one or more addresses, and customFieldEntries. It also carries pipeline state:

  • a phase — { id, name, displayName }, its stage in your pipeline (see Lead Phase)
  • a status — { value, displayName }, plus statusReason, source, and inquirySource

A lead converts to a project. Once it has been converted, the lead's projectId is populated and points at the resulting project — that field is your join between the two worlds.

Leads are soft-deleted via archiving rather than hard-deleted in normal use: an archived lead has an archivedAt timestamp and drops out of the active pipeline without being destroyed. (A permanent DELETE is also offered for leads that require it.)

Clients & contacts​

The people a project or lead belongs to live in the contacts system:

  • Contact — an individual or business in the company's address book, with email, phone, and address fields.
  • Contact Group — a named collection of contacts, typed HOMEOWNER or BUSINESS. A contact belongs to a group.
  • Contact Group Contact — the membership link between a contact and a group, at PRIMARY or SECONDARY level.

The client object embedded on a project or lead refers to this same set of people.

People & vendors​

The other parties a company works with:

  • Team Member — internal staff on the account, invited by email and given a role. Deactivating a team member does not permanently remove them.
  • Subcontractor — an external trade professional invited to collaborate, identified by one or more trades. See Subcontractor Trade for the reference list of disciplines (Electrical, Plumbing, HVAC, …).
  • Vendor — a supplier of materials, products, or services, with contact info, payment terms, and tax settings.

Custom fields​

Custom fields let you attach your own structured data to leads and projects — most importantly, your own system's IDs, so you can look a Houzz record up by it later. Two resources make this work:

  • CustomField — the definition (a name and type) scoped to an entity type.
  • CustomFieldEntry — a value for a definition, stored on a specific lead or project. Projects and leads return their values as a customFieldEntries array.

This external-ID mapping is the backbone of most integrations. See the Custom Fields guide for the full pattern.

Supporting resources​

  • Address — a postal address embedded inside a project, lead, or contact (via an addresses[] array). It is not a standalone endpoint; you upsert addresses through their parent resource.
  • Entity Assignment — assigns people (team members, subcontractors, contacts) to projects, leads, tasks, and milestones, and answers "who is assigned to X" and "what is X assigned to".

Reference lists​

Several read-only lists describe the vocabulary a company has configured. You read from them to resolve the IDs you send on writes:

ListEndpointUsed by
Project StatusGET /v1/project-statusesa project's statusId
Project TypeGET /v1/project-typesa project's projectType
Lead PhaseGET /v1/lead-phasesa lead's phaseId
Subcontractor TradeGET /v1/subcontractor-tradesa subcontractor's trades

ID conventions​

  • IDs are integers. Every resource is addressed by an integer id that is unique within your company. (A couple of reference objects — Project Type, and Team Member / Subcontractor — expose string IDs; treat those as opaque.)
  • Foreign keys use <resource>Id. You link records by passing integer foreign keys such as clientId, statusId, projectId, milestoneId, or punchlistId.

Timestamps​

Timestamp formats are not uniform across the API — check the field on each resource:

ResourceTimestamp formatExample fields
ProjectISO 8601 stringscreatedAt, updatedAt
Webhook SubscriptionISO 8601 stringscreatedAt, updatedAt
Leadepoch millisecondscreatedAt, updatedAt, archivedAt
Milestoneepoch millisecondsstartDate, dueDate
Taskepoch millisecondsdueDate, startDate, doneAt
Daily Logepoch millisecondslogDate, logEndDate

When you send a date on a lead, milestone, task, or daily log, pass epoch milliseconds. When you read a project's createdAt, expect an ISO 8601 string.

Common conventions​

These hold across every endpoint:

  • Authentication — every request carries an OAuth 2.0 Bearer token, issued per scope by the Houzz authorization server. See Authentication.
  • Pagination — list endpoints accept limit (default 20, max 300) and offset, and return { data, limit, offset, total }. See Pagination.
  • Errors — every error uses one envelope, { error: { code, message } }, with a standard HTTP status code. See Errors.
  • Archiving vs. delete — some resources are archived (hidden from active views but preserved, e.g. leads, vendors, files, contact groups), while others offer a permanent delete (e.g. contacts, and projects via an admin scope). Deactivation of team members and subcontractors is likewise reversible, not destructive. Prefer archiving when you need the record to survive; reach for delete only when removal must be permanent.

Next steps​