How to Use the Houzz Pro API — Beta

If you'd like to join the Houzz Pro API beta program, contact your Houzz representative or email us at dedicatedsupport@houzz.com.

The Houzz Pro API lets you build your own custom integrations between Houzz Pro and the other tools you use to run your business. It's designed for developers or technical users who are comfortable working with APIs. This article covers how to set up access in your Houzz Pro account.

For details on authentication, available endpoints, scopes, rate limits, and example requests, visit the Houzz Pro Developer Documentation.

Looking for a ready-made integration instead? Houzz Pro offers built-in connections with Mailchimp, Pipedrive, HubSpot and Zoho. See How to Connect Third-Party Apps.

What's New

The API now covers much more of your business, including your financial documents and reports:

  • Write access across your core records. Create, update and delete projects, leads, milestones, tasks, daily logs, files, contacts, vendors, team members and subcontractors.
  • Estimates, invoices, change orders and purchase orders (read-only). Includes line items, status, totals, amount paid and balance.
  • Expenses and time tracking (read-only).
  • Financial reports. Generate nine reports through the API, including Profitability, Open Invoices and Tax Liability.
  • Selections boards (read-only). Boards and their sections, including allowance and budget.
  • Catalog and sales tax (read-only). Cost codes, categories, catalog items, assemblies and your sales tax rates.
  • Notes on projects and leads. Read, create, update and archive.
  • Lead actions. Convert a lead to a project, retire or reactivate a lead, and move it to a different phase.
Before You Start

You'll need:

  • Permission to use API Integrations. Team members need an account owner or super admin to turn this on for them on the Team Permissions page.
  • To accept the Houzz API Terms of Use. Each person who uses API Management accepts the terms for themselves. Read the API Terms of Use.
  • Experience with REST APIs, or a developer who has it.
Create an API Client

To authenticate with the Houzz Pro API, you need to create an API client.

1. Click the Settings icon in the left navigation, then select API Management.

2. Click Create API Client.

3. Enter a Name and an optional Description for your API client so your team knows what the client is for. For example: "Website lead form."

4. Select the scopes your integration needs. Scopes control which Houzz Pro data your integration can read or change, so only turn on the ones you need.

5. Click Create API Client at the bottom of the page. Your Client ID and Client Secret will appear.

6. Copy your Client ID and Client Secret. You'll use them to authenticate your API requests.

Important: Keep your Client Secret private and treat it like a password. Don't share it or store it anywhere public.

Connect to the API

The API uses OAuth 2.0 with the client credentials flow. Your developer will:

  1. Request an access token by sending a POST to https://auth.houzz.com/oauth/token (form-encoded) with grant_type=client_credentials, your client_id and client_secret, audience=https://pro-api.houzz.com, and the scope values you need.
  2. Send that token in the Authorization: Bearer <token> header on every request. Tokens last 24 hours.
  3. Make calls to the base URL: https://pro-api.houzz.com/api. All endpoints start with /v1.

Example first call:

curl --request GET --url https://pro-api.houzz.com/api/v1/projects --header 'Authorization: Bearer <access_token>'

Step-by-step setup is in the Getting Started guide.

Delete an API Client


If you no longer need an API client, you can delete it.

  1. Click Edit on the API client you want to delete.
  2. Scroll to the bottom and click Delete [API client name].

Important: Deleting an API client can't be undone. Any integration still using its Client ID and Client Secret will stop syncing and show failed syncs. If you use the same API client for several integrations on the App Integrations page, all of them will stop working at once. Before you delete it, make sure no active integrations rely on it.

What You Can Access

Below are examples of the resource groups covered in the Houzz Pro API. Open the interactive API reference to explore and test every endpoint.

Read and Write

  • Projects: Projects, project statuses and project types. Read, create, update and delete.
  • Leads: Leads and lead phases. Read, create, update and delete. You can also convert a lead to a project, retire or reactivate it, and change its phase.
  • Notes: Notes on projects and leads. Read, create, update and archive.
  • Schedule: Milestones on projects and leads. Read, create, update and delete.
  • Tasks and punchlists: Tasks on projects and leads, and project punchlists. Read, create, update and delete.
  • Daily logs: Daily logs on projects. Read, create, update and delete.
  • Files: Files and folders on your company, projects and leads. Read, create, update and delete. You can also upload, copy, move and archive.
  • Contacts: Contacts and contact groups. Read, create, update and delete.
  • Vendors: Your vendors. Read, create, update and archive.
  • Team members: Your internal team. Read, invite, update and deactivate.
  • Subcontractors: Subcontractors and trades. Read, invite, update and deactivate.
  • Assignments: Who's assigned to projects, leads, tasks and milestones. Read and assign.
  • Custom fields: Custom field definitions and values. Read, create and update. You can also look up a record by a custom field value, such as an ID from another system.

Read-only (New)

  • Selections boards: Selections boards and their sections, including allowance and budget.
  • Financial documents: Estimates, invoices, change orders and purchase orders, with their line items.
  • Expenses: Your expenses.
  • Time tracking: Time your team has logged.
  • Catalog: Cost codes, categories, catalog items and assemblies.
  • Sales tax: Your company's sales tax rates.

Financial Reports (New)

You can generate and read these reports through the API:

  • Profitability
  • Open Invoices
  • Income Documents
  • Expense Documents
  • Income Payments
  • Expense Payments
  • Payouts
  • Time Entries
  • Tax Liability

Reports run in the background. Your integration starts a report, checks its status until it's complete, then fetches the results. You can filter most reports by date range and project.

Every endpoint, with its fields and filters, is listed in the interactive API reference.

Not Available Yet

The API can't do these yet:

  • Create or edit estimates, invoices, change orders or purchase orders
  • Send webhook events for financial documents or payments
  • Access calendar events
Scopes

Scopes control what an API client can do. Each area has up to three levels:

  • Read to view and list records
  • Write to create and update records
  • Admin to delete, archive or deactivate records

Areas with Read, Write and Admin Scopes

  • Projects: read:projects, write:projects, admin:projects
  • Leads: read:leads, write:leads, admin:leads
  • Schedule (milestones): read:schedule, write:schedule, admin:schedule
  • Tasks and punchlists: read:tasks, write:tasks, admin:tasks
  • Daily logs: read:daily-logs, write:daily-logs, admin:daily-logs
  • Files: read:files, write:files, admin:files
  • Contacts and contact groups: read:contacts, write:contacts, admin:contacts
  • Vendors: read:vendors, write:vendors, admin:vendors
  • Team members: read:team-members, write:team-members, admin:team-members
  • Subcontractors: read:subcontractors, write:subcontractors, admin:subcontractors

Areas with Read and Write Scopes

  • Assignments: read:entity-assignments, write:entity-assignments

Areas with Read Scopes Only

  • Selections boards: read:selections-boards
  • Estimates, invoices, change orders and purchase orders: read:documents
  • Expenses: read:expenses
  • Time tracking: read:time-tracks
  • Cost codes, categories and catalog items: read:catalog
  • Sales tax: read:sales-taxes
  • Financial reports: read:reports

Notes on projects and leads use the project or lead scopes. Webhooks and custom field definitions work with any valid token. To set a custom field value on a record, the client needs write access to that record type.

Get Updates in Real Time With Webhooks

Instead of checking Houzz Pro for changes over and over, your integration can subscribe to webhooks. Houzz Pro sends a signed POST to your HTTPS endpoint when something changes.

Events You Can Subscribe To:

  • Create, update and delete events: Clients, projects, leads, tasks, milestones, daily logs, files and contact groups.
  • Create and update events: Vendors, team members and subcontractors.

Good to Know:

  • Archiving a vendor, team member, subcontractor or file is sent as an update. A file's delete event is sent only when the file is permanently deleted from Trash.
  • When you create a subscription, you get a signing secret that's shown only once. Store it. If you lose it, delete the subscription and create a new one.
  • Verify every delivery using the X-Webhook-Signature and X-Webhook-Timestamp headers.
  • Respond with a 2xx status within 30 seconds, then do the processing afterward.
  • Events can arrive more than once and out of order. Use delivery_id to skip duplicates and occurred_at to put events in order.
  • Failed deliveries are retried for about 2.5 hours by default (up to about 32 hours if you raise the retry limit). A subscription turns off automatically after 10 events in a row fail.

Setup steps, payload format and signature verification are in the Webhooks guide.

Limits and Best Practices
  • Rate limits. Each company can make bursts of up to 45 requests, refilling at 15 requests per second. Some accounts also have a monthly request allowance. If you go over either limit, you'll get a 429 error. Wait and retry.
  • Paging. List endpoints return 20 results by default and up to 300 per page. Use limit and offset to page through results.
  • Errors. Errors return an error object with a code and a message. Handle errors by status code and error.code, not by the message text.
  • Versioning. All endpoints start with /v1. Breaking changes will come in a new version.
Still need help?