openHandwerk
API docs by Redocly

openHandwerk REST API (1.0.0)

Download OpenAPI specification:

openHandwerk Engineering: info@openhandwerk.de URL: https://www.openhandwerk.de License: Proprietary

The openHandwerk REST API provides programmatic access to the openHandwerk platform, enabling integration with craft-business management features such as customers, projects, appointments, documents, products, suppliers, and employee management.

Authentication

All endpoints (except /auth/login and /auth/register) require a valid JWT Bearer token in the Authorization header.

  1. Obtain a token via POST /auth/login.
  2. Include it in subsequent requests: Authorization: Bearer <token>.

The token is validated both as a JWT signature and against a server-side token store.

Response Envelope

Every JSON response follows a standard envelope:

{
  "success": true,
  "response": { ... },
  "status": 200
}

On error:

{
  "success": false,
  "response": "Error message",
  "status": 400
}

Auth

Authentication and token management

Authenticate and obtain a JWT token

Validates the provided credentials against the openHandwerk account store. On success, returns a JWT bearer token that must be included in the Authorization header of all subsequent requests.

Request Body schema: application/json
required
idKn
required
string

Account / tenant identifier.

employee
required
string

Employee username or identifier within the tenant.

password
required
string <password>

User password.

Responses

Request samples

Content type
application/json
{
  • "idKn": "ACME-001",
  • "employee": "jdoe",
  • "password": "s3cret!"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJBQ01FLTAwMS06Oi1qZG9lIiwiaWF0IjoxNzExMDAwMDAwLCJleHAiOjE3MTEwODY0MDB9.XXXX",
  • "status": 200
}

Register a new API user

Creates a new API user account within the specified tenant. The user will be able to log in via POST /auth/login after registration.

Request Body schema: application/json
required
idKn
required
string

Account / tenant identifier.

email
required
string <email>

User e-mail address.

employee
required
string

Employee username.

password
required
string <password>

Desired password.

Responses

Request samples

Content type
application/json
{
  • "idKn": "ACME-001",
  • "email": "jdoe@example.com",
  • "employee": "jdoe",
  • "password": "s3cret!"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": "new user created successfully",
  • "status": 200
}

Resolve a token to its account

Looks up the given token string in the token store and returns the associated account identifier.

Authorizations:
BearerAuth
query Parameters
token
required
string
Example: token=eyJhbGciOiJIUzI1NiIs...

The JWT token string to look up.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Health / debug check

Returns a simple ok response to verify the API is running and authentication is working.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Employees

Employee / user management

List employees

Returns all employees for the authenticated tenant. Supports optional filtering by email, name, company, and role.

Authorizations:
BearerAuth
query Parameters
eamil
string
Example: eamil=jdoe@example.com

Filter by employee email address (LIKE match). Note — parameter name reflects the API implementation.

name
string
Example: name=Doe

Filter by employee name (LIKE match).

company
string
Example: company=ACME

Filter by company name (LIKE match).

role
string
Enum: "Administrator" "App" "Employee"
Example: role=Administrator

Filter by role. Accepted values: Administrator, App (maps to App User), Employee. Invalid values default to Employee.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": [
    ],
  • "status": 200
}

Get a single employee

Returns detailed information about a single employee by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 7

Employee ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Projects

Combined project listing (orders + offers)

List all projects (orders + offers)

Returns a combined listing of both orders and offers for the authenticated tenant. Use the type parameter to filter to only orders or only offers.

Authorizations:
BearerAuth
query Parameters
reference_number
string
Example: reference_number=ORD-2025

Filter by reference number (LIKE match).

project_name
string
Example: project_name=Kitchen

Filter by project name (LIKE match).

id
integer
Example: id=101

Filter by exact project ID.

type
string
Enum: "order" "orders" "offer" "offers"

Restrict results to only orders or only offers.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Search projects by term

Searches across both orders and offers for a matching project. Returns the first matching result.

Authorizations:
BearerAuth
Request Body schema: application/json
required
projectTerm
required
string

Search term to match against project name, reference number, etc.

Responses

Request samples

Content type
application/json
{
  • "projectTerm": "Kitchen Renovation"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Advanced multi-field project search

Provides granular search across orders and offers using multiple filter fields. Results include standard rows for orders and extended rows (with nested tenant, address, client, and dates) for offers.

Authorizations:
BearerAuth
Request Body schema: application/json
required
tenant_name
string
tenant_email
string
tenant_phone
string
order_number
string
project_name
string
street
string
zip
string
city
string
country
string
reference_number
string
customer_number
string
company
string
contact_person
string
client_name
string
branch
string
search_type
string
Default: "all"
Enum: "all" "orders" "offers"

Restrict results to orders, offers, or both.

Responses

Request samples

Content type
application/json
{
  • "tenant_name": "Mustermann",
  • "city": "Berlin",
  • "search_type": "all"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Create a new project / order

Creates a new project by proxying the request to the openHandwerk cloud backend. Requires both a project and customer object in the request body.

Authorizations:
BearerAuth
Request Body schema: application/json
required
project
required
object

Project / order details forwarded to the openHandwerk backend.

customer
required
object

Customer details for the new project.

Responses

Request samples

Content type
application/json
{
  • "project": {
    },
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": { },
  • "status": 200
}

Orders

Order (Auftrag) management

List all orders

Returns all orders (Aufträge) for the authenticated tenant with optional filters.

Authorizations:
BearerAuth
query Parameters
reference_number
string

Filter by reference number (LIKE match).

project_name
string

Filter by project name (LIKE match).

id
integer

Filter by exact order ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": [
    ],
  • "status": 200
}

Get a single order

Returns detailed information about a specific order by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 101

Order ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Offers

Offer (Angebot) management

List all offers

Returns all offers (Angebote) for the authenticated tenant with optional filters.

Authorizations:
BearerAuth
query Parameters
reference_number
string

Filter by reference number (LIKE match).

project_name
string

Filter by project name (LIKE match).

id
integer

Filter by exact offer ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": [
    ],
  • "status": 200
}

Get a single offer

Returns detailed information about a specific offer by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 202

Offer ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Customers

Customer (Kunde) management

List customers

Returns all customers for the authenticated tenant. Supports a wide range of optional LIKE filters and category-based filtering.

Authorizations:
BearerAuth
query Parameters
company
string

Filter by company name (LIKE).

city
string

Filter by city (LIKE).

country
string

Filter by country (LIKE).

branch
string

Filter by branch (LIKE).

email
string

Filter by email (LIKE).

customer_reference
string

Filter by customer reference (LIKE).

website
string

Filter by website (LIKE).

address
string

Filter by street address (LIKE, maps to street column).

zip
string

Filter by postal code (LIKE).

first_name
string

Filter by first name (LIKE).

last_name
string

Filter by last name (LIKE).

phone
string

Filter by phone number (LIKE).

mobile
string

Filter by mobile number (LIKE).

fax
string

Filter by fax number (LIKE).

phone_private
string

Filter by private phone number (LIKE).

contact_person
string

Filter by contact person (LIKE).

id
integer

Filter by exact customer ID.

polling
string
Enum: "1" "true"

If truthy, returns only customers created in the last 24 hours.

category
string
Enum: "Auftraggeber" "Rechnungsempfänger" "Leistungsempfänger" "Lieferscheinempfänger" "Leistungsscheinempfänger"

Filter by customer category (German category name).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": [
    ],
  • "status": 200
}

Get a single customer

Returns detailed information about a single customer by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 501

Customer ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Quick-search customers

Performs a quick search across customer names, companies, and emails using the provided search term in the URL path.

Authorizations:
BearerAuth
path Parameters
searchTerm
required
string
Example: Muster

The search term to match.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Search customers

Searches customers by a given term with optional exact-match mode. The search is performed across name, company, email, and other key fields.

Authorizations:
BearerAuth
Request Body schema: application/json
required
search
required
string

Search term (applied to name, company, email, etc.).

exact_match
boolean
Default: false

If true, performs an exact-match search instead of LIKE.

Responses

Request samples

Content type
application/json
{
  • "search": "Mustermann",
  • "exact_match": false
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Create a customer

Creates a new customer record for the authenticated tenant. The type field is required to distinguish between company and person contacts.

Authorizations:
BearerAuth
Request Body schema: application/json
required
type
required
string
Enum: "company" "person"

Whether this customer is a company or natural person.

first_name
string
last_name
string
salutation
string
company
string
branch
string
email
string <email>
street
string

Street name.

street_nr
integer

House number.

zip
integer
city
string
country
string
co
string
customer_reference
string
phone_private
string
fax
string
tax_id
string
ust_id
string
tax_category
integer [ 1 .. 9 ]

Responses

Request samples

Content type
application/json
{
  • "type": "company",
  • "first_name": "Max",
  • "last_name": "Mustermann",
  • "company": "Musterbau GmbH",
  • "email": "max@example.com",
  • "street": "Musterstraße",
  • "street_nr": 12,
  • "zip": 10115,
  • "city": "Berlin",
  • "country": "Deutschland"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Update a customer

Partially updates an existing customer. Only the provided fields will be modified.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 501

Customer ID.

Request Body schema: application/json
required
type
string
Enum: "company" "person"
first_name
string
last_name
string
salutation
string
company
string
branch
string
email
string <email>
street
string
street_nr
integer
zip
integer
city
string
country
string
co
string
customer_reference
string
phone_private
string
fax
string
tax_id
string
ust_id
string
tax_category
integer [ 1 .. 9 ]

Responses

Request samples

Content type
application/json
{
  • "email": "updated@example.com",
  • "city": "Munich"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Suppliers

Supplier (Lieferant) management

List suppliers

Returns all suppliers for the authenticated tenant.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": [
    ],
  • "status": 200
}

Get a single supplier

Returns detailed information about a single supplier by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 301

Supplier ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Create a supplier

Creates a new supplier record. first_name and last_name are required. Optionally pass a ligId to create an external LIG reference.

Authorizations:
BearerAuth
Request Body schema: application/json
required
first_name
required
string
last_name
required
string
salutation
string
email
string <email>
phone
string
website
string
street
string
street_number
string
zip
string
city
string
country
string
company
string
branch
string
ligId
string

Optional external reference ID for LIG integration.

Responses

Request samples

Content type
application/json
{
  • "first_name": "Hans",
  • "last_name": "Lieferant",
  • "company": "Lieferant GmbH",
  • "email": "hans@lieferant.de",
  • "street": "Lieferstraße",
  • "street_number": "5",
  • "zip": "10117",
  • "city": "Berlin",
  • "country": "Deutschland"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Update a supplier

Partially updates an existing supplier. Only the provided fields will be modified.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 301

Supplier ID.

Request Body schema: application/json
required
first_name
string
last_name
string
salutation
string
email
string <email>
phone
string
website
string
street
string
street_number
string
zip
string
city
string
country
string
company
string
branch
string

Responses

Request samples

Content type
application/json
{
  • "email": "updated@lieferant.de",
  • "city": "Hamburg"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Delete a supplier

Permanently deletes a supplier by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 301

Supplier ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Products

Product / service-item management

List products

Returns all products / service items for the authenticated tenant.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": [
    ],
  • "status": 200
}

Get a single product

Returns detailed information about a single product by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 401

Product ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Create a product

Creates a new product / service item. Optionally pass a ligId to create an external LIG reference.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string
unit
required
string
unit_price
required
number <float>
buying_price
required
number <float>
ust
number <float>

VAT rate as decimal (e.g. 0.19). Stored internally as integer hundredths.

product_reference
string
long_text
string
manufacturer_name
string
category
string
supplier_name
string
ligId
string

Optional external reference ID for LIG integration.

Responses

Request samples

Content type
application/json
{
  • "name": "Sanitärinstallation Standard",
  • "unit": "Stk",
  • "unit_price": 125.5,
  • "buying_price": 85,
  • "ust": 0.19,
  • "manufacturer_name": "Grohe",
  • "category": "Sanitär"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Update a product

Partially updates an existing product. Only the provided fields will be modified.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 401

Product ID.

Request Body schema: application/json
required
name
string
unit
string
unit_price
number <float>
buying_price
number <float>
ust
number <float>
product_reference
string
long_text
string
manufacturer_name
string
category
string
supplier_name
string

Responses

Request samples

Content type
application/json
{
  • "unit_price": 130,
  • "ust": 0.19
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Delete a product

Permanently deletes a product by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 401

Product ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Calendar

Calendar categories

List appointment categories

Returns all available appointment/calendar categories. Optionally filter by category name.

Authorizations:
BearerAuth
query Parameters
name
string
Example: name=Kundentermin

Filter by category name (LIKE match).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": [
    ],
  • "status": 200
}

Appointments

Appointment / event management

List appointments

Returns all appointments for the authenticated tenant. Supports filtering by various fields including employee email.

Authorizations:
BearerAuth
query Parameters
email
string <email>
Example: email=jdoe@example.com

Filter by employee email — resolves the employee and filters appointments where they are an attendee.

title
string

Filter by title (LIKE match).

description
string

Filter by description (LIKE match).

address
string

Filter by address (LIKE match).

project_id
integer

Filter by associated project ID (exact match).

category_id
integer

Filter by category ID (exact match).

id
integer

Filter by exact appointment ID.

polling
string
Enum: "1" "true"

If truthy, returns only recently created/updated appointments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": [
    ],
  • "status": 200
}

Get a single appointment

Returns detailed information about a single appointment by ID, including attendees and category.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 601

Appointment ID.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Create an appointment

Creates a new appointment/calendar event. Attendees are specified as an array of employee IDs that will be resolved to full employee records.

Authorizations:
BearerAuth
Request Body schema: application/json
required
start
required
string <date-time>
end
required
string <date-time>
title
required
string
category_id
required
integer

ID of the appointment category (or use built-in string IDs like TASK, VACATION).

project_id
integer

Optional associated project/order ID.

description
string
address
string
all_day
boolean
Default: false
attendees
Array of integers

Array of employee IDs to assign as attendees.

Responses

Request samples

Content type
application/json
{
  • "start": "2025-04-15T09:00:00",
  • "end": "2025-04-15T10:30:00",
  • "title": "On-site inspection",
  • "category_id": 1,
  • "project_id": 101,
  • "description": "Inspect bathroom for renovation",
  • "address": "Musterstraße 12, 10115 Berlin",
  • "all_day": false,
  • "attendees": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}

Update an appointment

Partially updates an existing appointment. Only the provided fields will be modified.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 601

Appointment ID.

Request Body schema: application/json
required
start
string <date-time>
end
string <date-time>
title
string
category_id
integer
project_id
integer
description
string
address
string
all_day
boolean
attendees
Array of integers

Responses

Request samples

Content type
application/json
{
  • "title": "Updated inspection",
  • "end": "2025-04-15T11:00:00"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "response": {
    },
  • "status": 200
}