---
title: "Overview"
description: "Connect your own systems to Bauhow through the REST API: contacts, deals, projects and project modules."
---

:::warning
**The API is in early access.** It is enabled per workspace on request. Please request access through [Bauhow support](https://bauhow.com/support) before you build an integration. Until then the **API** settings page is hidden, so no keys can be created yet. Requests without a valid key get `401`; keys of a workspace without access get `403`.
:::

The Bauhow API connects your ERP, CRM, accounting or website to your workspace. It is a JSON REST API with an OpenAPI description.

**[API reference](/en/api/reference)**

Every endpoint with parameters, responses and code samples.

**[Request access](https://bauhow.com/support)**

Have the API enabled for your workspace.

## What the API covers

| Area | Capabilities |
|---|---|
| Contacts and buildings | Read, create, update and delete contacts including custom fields; read and create buildings |
| Deals | Read, create, move between stages, win or lose, archive and delete deals; read stages and project types; set a stage's probability and critical threshold |
| Projects | Read, create, rename, set the status, archive and restore projects |
| Project modules | Read a project's modules and change their inputs, for example in the funding calculator |
| Photovoltaics | Read and create a project's PV plans |

Base URL:

```text
https://app.bauhow.com/api/v1
```

## Create an API key

Once the API is enabled, owners and admins create keys:

1. **Open settings**

    Open **Settings → Workspace → API**.

2. **Create a key**

    Click **Create key**, enter a name and choose **No access**, **Read** or **Read and write** per area. Set how long the key stays valid.

3. **Copy the key**

    Copy the key right away. It is shown only once. Store it somewhere safe, for example in a password manager.

Send the key with every request in the `Authorization` header:

```bash
curl https://app.bauhow.com/api/v1/projects \
  -H "Authorization: Bearer bh_…"
```

## Permissions

A key acts with the permissions of the member who created it, limited to the selected areas. If that member only sees assigned contacts or projects, so does the key. Plan limits apply as in the app.

| Area | Read | Read and write |
|---|---|---|
| Contacts and buildings | `contacts:read` | `contacts:write` |
| Deals | `deals:read` | `deals:write` |
| Projects, modules and PV plans | `projects:read` | `projects:write` |

:::info
The key stops working when that member leaves the workspace or is deactivated. Create keys for long-running integrations from an account that stays.
:::

Under **Settings → Workspace → API**, owners and admins see every key with its creator, expiry and last use. **Revoke** blocks a key immediately.

## Lists and syncing

The contact, building, deal and project lists return `{ "data": [...], "hasMore": true }` and support `limit` (up to 500), `offset` and `updatedSince`. `updatedSince` returns only records changed since a point in time. The other lists (modules, PV plans, contact fields, stages, project types) are short and always return every entry as `{ "data": [...] }`.

```bash
curl "https://app.bauhow.com/api/v1/contacts?updatedSince=2026-10-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer bh_…"
```

Custom contact fields are in the `fields` object, keyed by field key. `GET /v1/contact-fields` lists them.

## Errors

| Status | Meaning |
|---|---|
| `400` | Invalid input, for example an unknown contact field |
| `401` | Key missing, revoked or expired |
| `403` | API not enabled for the workspace, missing area, role does not allow the action, or plan limit reached |
| `404` | Record not found or not visible to the key |
