Bleno REST API

Connect website forms, enquiry portals, time clocks or your own software to Bleno: create customers, projects and leads, retrieve quotes and invoices, transfer time entries.

Version 1.0.0

The API reference below is generated from the specification. The JSON specification itself describes the fields in German.

Authentication

REST API for customers, projects, leads, quotes/invoices, time entries and webhooks of a Bleno business.

Authentication with an API key (Authorization: Bearer bleno_…). Every key carries scopes per resource (read/write); a missing scope results in 403.

Rate limit: 60 calls per key and 60 seconds, above that 429 with Retry-After.

Administrators create a key under “Einstellungen → API & Webhooks” (settings) and choose its scopes there. The key is shown only once. Data of other businesses is never reachable: IDs of another business return 404 like unknown ones, and an empty list when used as a filter.

The machine-readable description for code generators and API tools: OpenAPI specification (JSON, descriptions in German)

curl https://bleno.de/api/v1/customers \
  -H "Authorization: Bearer bleno_…"
Scopes
AreaReadWrite
Customerscustomers:readcustomers:write
Projectsprojects:readprojects:write
Leadsleads:readleads:write
Documentsdocuments:readdocuments:write
Time entriestime_entries:readtime_entries:write
Webhookswebhooks:readwebhooks:write

Customers

Read, create and update the business’s customers.

GET/api/v1/customers

List customers

Paginated; archived customers only with include_archived=true.

Required scope: customers:read.

Scope: customers:read

Parameters
FieldTypeRequiredNotes
limit(query)integernoDefault: 50 · min. 1 · max. 100
offset(query)integernoDefault: 0 · min. 0
include_archived(query)"true" | "false"noDefault: "false"

Responses

  • 200 Customer list.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
dataobject[]yes
data[].idstring (uuid)yes
data[].customer_numberstring | nullyes
data[].customer_type"company" | "private"yes
data[].salutation"herr" | "frau" | nullyes
data[].company_namestring | nullyes
data[].first_namestring | nullyes
data[].last_namestring | nullyes
data[].display_namestringyes
data[].emailstring | nullyes
data[].phonestring | nullyes
data[].mobile_phonestring | nullyes
data[].faxstring | nullyes
data[].address_streetstring | nullyes
data[].address_zipstring | nullyes
data[].address_citystring | nullyes
data[].tax_idstring | nullyes
data[].notesstring | nullyes
data[].is_archivedbooleanyes
data[].created_atstringyes
data[].updated_atstring | nullyes
paginationobjectyes
pagination.limitintegeryes
pagination.offsetintegeryes
pagination.totalintegeryes
POST/api/v1/customers

Create a customer

Without customer_type: a company if a company name is given, otherwise a private person. Required fields as in the customer form.

Required scope: customers:write.

Scope: customers:write

Request (JSON)
FieldTypeRequiredNotes
customer_type"company" | "private"no
salutation"herr" | "frau" | nullno
company_namestring | nullnoat most 200 characters
first_namestring | nullnoat most 100 characters
last_namestring | nullnoat most 100 characters
emailstring (email) | "" | any | nullno
customer_numberstring | nullnoat most 50 characters
phonestring | nullnoat most 50 characters
mobile_phonestring | nullnoat most 50 characters
faxstring | nullnoat most 50 characters
address_streetstring | nullnoat most 200 characters
address_zipstring | nullnoat most 20 characters
address_citystring | nullnoat most 100 characters
tax_idstring | nullnoat most 50 characters
notesstring | nullnoat most 5000 characters

Responses

  • 201 Customer created.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 409 Conflict, e.g. a duplicate customer or project number or a time entry that has already been invoiced.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 201
FieldTypeRequiredNotes
dataobjectyes
data.idstring (uuid)yes
data.customer_numberstring | nullyes
data.customer_type"company" | "private"yes
data.salutation"herr" | "frau" | nullyes
data.company_namestring | nullyes
data.first_namestring | nullyes
data.last_namestring | nullyes
data.display_namestringyes
data.emailstring | nullyes
data.phonestring | nullyes
data.mobile_phonestring | nullyes
data.faxstring | nullyes
data.address_streetstring | nullyes
data.address_zipstring | nullyes
data.address_citystring | nullyes
data.tax_idstring | nullyes
data.notesstring | nullyes
data.is_archivedbooleanyes
data.created_atstringyes
data.updated_atstring | nullyes
GET/api/v1/customers/{id}

Retrieve a customer

Required scope: customers:read.

Scope: customers:read

Parameters
FieldTypeRequiredNotes
id(path)string (uuid)yes

Responses

  • 200 Customer.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 404 Not found – also for IDs of another business.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
dataobjectyes
data.idstring (uuid)yes
data.customer_numberstring | nullyes
data.customer_type"company" | "private"yes
data.salutation"herr" | "frau" | nullyes
data.company_namestring | nullyes
data.first_namestring | nullyes
data.last_namestring | nullyes
data.display_namestringyes
data.emailstring | nullyes
data.phonestring | nullyes
data.mobile_phonestring | nullyes
data.faxstring | nullyes
data.address_streetstring | nullyes
data.address_zipstring | nullyes
data.address_citystring | nullyes
data.tax_idstring | nullyes
data.notesstring | nullyes
data.is_archivedbooleanyes
data.created_atstringyes
data.updated_atstring | nullyes
PATCH/api/v1/customers/{id}

Update a customer

Only the fields you send change; null clears a field.

Required scope: customers:write.

Scope: customers:write

Parameters
FieldTypeRequiredNotes
id(path)string (uuid)yes
Request (JSON)
FieldTypeRequiredNotes
customer_type"company" | "private"no
salutation"herr" | "frau" | nullno
company_namestring | nullnoat most 200 characters
first_namestring | nullnoat most 100 characters
last_namestring | nullnoat most 100 characters
emailstring (email) | "" | any | nullno
customer_numberstring | nullnoat most 50 characters
phonestring | nullnoat most 50 characters
mobile_phonestring | nullnoat most 50 characters
faxstring | nullnoat most 50 characters
address_streetstring | nullnoat most 200 characters
address_zipstring | nullnoat most 20 characters
address_citystring | nullnoat most 100 characters
tax_idstring | nullnoat most 50 characters
notesstring | nullnoat most 5000 characters

Responses

  • 200 Updated customer.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 404 Not found – also for IDs of another business.
  • 409 Conflict, e.g. a duplicate customer or project number or a time entry that has already been invoiced.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
dataobjectyes
data.idstring (uuid)yes
data.customer_numberstring | nullyes
data.customer_type"company" | "private"yes
data.salutation"herr" | "frau" | nullyes
data.company_namestring | nullyes
data.first_namestring | nullyes
data.last_namestring | nullyes
data.display_namestringyes
data.emailstring | nullyes
data.phonestring | nullyes
data.mobile_phonestring | nullyes
data.faxstring | nullyes
data.address_streetstring | nullyes
data.address_zipstring | nullyes
data.address_citystring | nullyes
data.tax_idstring | nullyes
data.notesstring | nullyes
data.is_archivedbooleanyes
data.created_atstringyes
data.updated_atstring | nullyes

Projects

Read and create projects.

GET/api/v1/projects

List projects

All projects that are not archived, with customer and status, sorted by name.

Required scope: projects:read.

Scope: projects:read

Responses

  • 200 Project list.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
projectsobject[]yes
projects[].idstring (uuid)yes
projects[].namestringyes
projects[].status"planned" | "ready_for_work" | "in_progress" | "completed" | "cancelled" | "on_hold"yes
projects[].customerobject | nullyes
projects[].customer.idstring (uuid)yes
projects[].customer.namestringyes
POST/api/v1/projects

Create a project

If the business uses automatic project numbers, Bleno assigns the next number when none is sent.

Required scope: projects:write.

Scope: projects:write

Request (JSON)
FieldTypeRequiredNotes
namestringyesat least 1 characters · at most 200 characters
customer_idstring (uuid)yes
descriptionstring | nullnoat most 5000 characters
status"planned" | "ready_for_work" | "in_progress" | "completed" | "cancelled" | "on_hold"no
project_type"fixed_fee" | "time_and_materials" | "non_billable"no
project_numberstring | nullnoat most 60 characters
start_datestring | nullnoPattern ^\d{4}-\d{2}-\d{2}$
end_datestring | nullnoPattern ^\d{4}-\d{2}-\d{2}$
address_streetstring | nullnoat most 200 characters
address_zipstring | nullnoat most 20 characters
address_citystring | nullnoat most 100 characters

Responses

  • 201 Project created.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 404 Not found – also for IDs of another business.
  • 409 Conflict, e.g. a duplicate customer or project number or a time entry that has already been invoiced.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 201
FieldTypeRequiredNotes
dataobjectyes
data.idstring (uuid)yes
data.namestringyes
data.project_numberstring | nullyes
data.status"planned" | "ready_for_work" | "in_progress" | "completed" | "cancelled" | "on_hold"yes
data.project_type"fixed_fee" | "time_and_materials" | "non_billable" | nullyes
data.customer_idstring (uuid)yes
data.descriptionstring | nullyes
data.start_datestring | nullyes
data.end_datestring | nullyes
data.address_streetstring | nullyes
data.address_zipstring | nullyes
data.address_citystring | nullyes
data.created_atstringyes

Leads

Create leads from website forms and portals.

POST/api/v1/leads

Create a lead

For website forms and enquiry portals. New leads start with status new and source website.

Required scope: leads:write.

Scope: leads:write

Request (JSON)
FieldTypeRequiredNotes
namestringyesat least 1 characters · at most 200 characters
emailstring (email) | "" | any | nullno
phonestring | nullnoat most 50 characters
notesstring | nullnoat most 5000 characters
customer_idstring (uuid) | nullno
external_referencestring | nullnoat most 200 characters

Responses

  • 201 Lead created.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 404 Not found – also for IDs of another business.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 201
FieldTypeRequiredNotes
dataobjectyes
data.idstring (uuid)yes
data.namestringyes
data.emailstring | nullyes
data.phonestring | nullyes
data.notesstring | nullyes
data.status"new" | "contacted" | "quote_sent" | "won" | "lost"yes
data.source"whatsapp" | "voice" | "test" | "website" | nullyes
data.customer_idstring (uuid) | nullyes
data.project_idstring (uuid) | nullyes
data.external_referencestring | nullyes
data.created_atstringyes

Documents

Read quotes and invoices with status, amounts and PDF link.

GET/api/v1/documents

List quotes and invoices

Filterable by type, status, customer and project. The list contains no PDF links.

Required scope: documents:read.

Scope: documents:read

Parameters
FieldTypeRequiredNotes
limit(query)integernoDefault: 50 · min. 1 · max. 100
offset(query)integernoDefault: 0 · min. 0
type(query)"quote" | "invoice"no
status(query)"draft" | "published" | "sent" | "accepted" | "rejected" | "lost" | "partially_paid" | "paid" | "cancelled"no
customer_id(query)string (uuid)no
project_id(query)string (uuid)no

Responses

  • 200 Document list.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
dataobject[]yes
data[].idstring (uuid)yes
data[].numberstring | nullyes
data[].type"quote" | "invoice"yes
data[].invoice_kind"partial" | "final" | nullyes
data[].status"draft" | "published" | "sent" | "accepted" | "rejected" | "lost" | "partially_paid" | "paid" | "cancelled"yes
data[].datestring | nullyes
data[].due_datestring | nullyes
data[].currencystringyes
data[].net_amountnumber | nullyes
data[].tax_ratenumber | nullyes
data[].tax_amountnumber | nullyes
data[].gross_amountnumber | nullyes
data[].customer_idstring (uuid) | nullyes
data[].project_idstring (uuid) | nullyes
data[].has_pdfbooleanyes
data[].created_atstringyes
data[].updated_atstring | nullyes
paginationobjectyes
pagination.limitintegeryes
pagination.offsetintegeryes
pagination.totalintegeryes
GET/api/v1/documents/{id}

Retrieve a quote or invoice

With PDF link: time-limited, and when it is opened Bleno asks for the customer’s postcode.

Required scope: documents:read.

Scope: documents:read

Parameters
FieldTypeRequiredNotes
id(path)string (uuid)yes

Responses

  • 200 Document.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 404 Not found – also for IDs of another business.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
dataobjectyes
data.idstring (uuid)yes
data.numberstring | nullyes
data.type"quote" | "invoice"yes
data.invoice_kind"partial" | "final" | nullyes
data.status"draft" | "published" | "sent" | "accepted" | "rejected" | "lost" | "partially_paid" | "paid" | "cancelled"yes
data.datestring | nullyes
data.due_datestring | nullyes
data.currencystringyes
data.net_amountnumber | nullyes
data.tax_ratenumber | nullyes
data.tax_amountnumber | nullyes
data.gross_amountnumber | nullyes
data.customer_idstring (uuid) | nullyes
data.project_idstring (uuid) | nullyes
data.has_pdfbooleanyes
data.created_atstringyes
data.updated_atstring | nullyes
data.pdfobject | nullyes
data.pdf.urlstring (uri)yes
data.pdf.expires_atstringyes
data.pdf.requires_postal_codetrueyes

Time entries

Read time entries and transfer them from terminals or third-party systems.

GET/api/v1/time-entries

List time entries

Entries in the period from to to, optionally for one employee.

Required scope: time_entries:read.

Scope: time_entries:read

Parameters
FieldTypeRequiredNotes
from(query)stringyesPattern ^\d{4}-\d{2}-\d{2}$
to(query)stringyesPattern ^\d{4}-\d{2}-\d{2}$
user_id(query)string (uuid)no
limit(query)integernoValues above 500 are capped at 500. · Default: 200 · min. 1 · max. 500
offset(query)integernoDefault: 0 · min. 0

Responses

  • 200 Time entries.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
entriesobject[]yes
entries[].idstring (uuid)yes
entries[].user_idstring (uuid) | nullyes
entries[].project_idstring (uuid)yes
entries[].datestringyes
entries[].start_timestring | nullyes
entries[].end_timestring | nullyes
entries[].break_minutesintegeryes
entries[].duration_minutesintegeryes
entries[].work_type"arbeiten" | "laden" | "fahren" | "pause"yes
entries[].descriptionstring | nullyes
entries[].is_billableboolean | nullyes
entries[].status"pending" | "approved" | "rejected" | "invoiced"yes
entries[].external_sourcestring | nullyes
entries[].external_idstring | nullyes
entries[].projectobject | nullyes
entries[].project.idstring (uuid)yes
entries[].project.namestringyes
has_morebooleanyes
POST/api/v1/time-entries

Transfer a time entry

Either duration_minutes or start_time and end_time. With external_source and external_id, a repeated call updates the same entry instead of creating a second one. Approval is up to the business.

Required scope: time_entries:write.

Scope: time_entries:write

Request (JSON)
FieldTypeRequiredNotes
user_idstring (uuid)yes
project_idstring (uuid)yes
datestringyesPattern ^\d{4}-\d{2}-\d{2}$
work_type"arbeiten" | "laden" | "fahren" | "pause"noDefault: "arbeiten"
start_timestringnoPattern ^\d{1,2}:\d{2}$
end_timestringnoPattern ^\d{1,2}:\d{2}$
break_minutesnumbernomin. 0
duration_minutesnumbernomin. 0 · max. 1440
descriptionstringno
is_billablebooleanno
external_sourcestringno
external_idstringno

Responses

  • 200 Existing entry from the same source updated.
  • 201 Time entry created (`created`); for a known source 200 with `updated`.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 404 Not found – also for IDs of another business.
  • 409 Conflict, e.g. a duplicate customer or project number or a time entry that has already been invoiced.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
action"created" | "updated"yes
idstring (uuid)yes
Response 201
FieldTypeRequiredNotes
action"created" | "updated"yes
idstring (uuid)yes

Webhooks

Subscribe to outgoing webhooks for Zapier, Make and your own receivers.

GET/api/v1/webhooks

List webhooks

The business’s endpoints without signing secret. Connection test for Zapier and Make.

Required scope: webhooks:read.

Scope: webhooks:read

Responses

  • 200 Endpoints.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 200
FieldTypeRequiredNotes
dataobject[]yes
data[].idstring (uuid)yes
data[].urlstringyes
data[].descriptionstring | nullyes
data[].eventsstring[]yes
data[].is_activebooleanyes
POST/api/v1/webhooks

Subscribe to a webhook

Creates an endpoint. Zapier sends target_url and event, other clients url and events. The signing secret appears only in this response.

Required scope: webhooks:write.

Scope: webhooks:write

Request (JSON)
FieldTypeRequiredNotes
urlstringno
target_urlstringno
event"customer.created" | "project.created" | "project.status_changed" | "lead.created" | "quote.accepted" | "quote.rejected" | "invoice.sent" | "invoice.paid" | "time_entry.created"no
events"customer.created" | "project.created" | "project.status_changed" | "lead.created" | "quote.accepted" | "quote.rejected" | "invoice.sent" | "invoice.paid" | "time_entry.created"[]no
descriptionstringnoat most 200 characters

Responses

  • 201 Endpoint created.
  • 400 Invalid input.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 429 Too many requests for this key.
  • 500 Internal error.
Response 201
FieldTypeRequiredNotes
dataobjectyes
data.idstring (uuid)yes
data.urlstringyes
data.events"customer.created" | "project.created" | "project.status_changed" | "lead.created" | "quote.accepted" | "quote.rejected" | "invoice.sent" | "invoice.paid" | "time_entry.created"[]yes
data.secretstringyes
DELETE/api/v1/webhooks/{id}

Unsubscribe from a webhook

Removes an endpoint. An unknown ID or one from another business is 404.

Required scope: webhooks:write.

Scope: webhooks:write

Parameters
FieldTypeRequiredNotes
id(path)string (uuid)yes

Responses

  • 204 Endpoint removed.
  • 401 API key missing, unknown or revoked. Empty body.
  • 403 The key lacks the required scope.
  • 404 Not found – also for IDs of another business.
  • 429 Too many requests for this key.
  • 500 Internal error.

Data models

Error

Fields
FieldTypeRequiredNotes
errorstringyes

ValidationError

Fields
FieldTypeRequiredNotes
errorstringyes
fieldsobjectyes

Customer

Fields
FieldTypeRequiredNotes
idstring (uuid)yes
customer_numberstring | nullyes
customer_type"company" | "private"yes
salutation"herr" | "frau" | nullyes
company_namestring | nullyes
first_namestring | nullyes
last_namestring | nullyes
display_namestringyes
emailstring | nullyes
phonestring | nullyes
mobile_phonestring | nullyes
faxstring | nullyes
address_streetstring | nullyes
address_zipstring | nullyes
address_citystring | nullyes
tax_idstring | nullyes
notesstring | nullyes
is_archivedbooleanyes
created_atstringyes
updated_atstring | nullyes

Project

Fields
FieldTypeRequiredNotes
idstring (uuid)yes
namestringyes
project_numberstring | nullyes
status"planned" | "ready_for_work" | "in_progress" | "completed" | "cancelled" | "on_hold"yes
project_type"fixed_fee" | "time_and_materials" | "non_billable" | nullyes
customer_idstring (uuid)yes
descriptionstring | nullyes
start_datestring | nullyes
end_datestring | nullyes
address_streetstring | nullyes
address_zipstring | nullyes
address_citystring | nullyes
created_atstringyes

ProjectListItem

Fields
FieldTypeRequiredNotes
idstring (uuid)yes
namestringyes
status"planned" | "ready_for_work" | "in_progress" | "completed" | "cancelled" | "on_hold"yes
customerobject | nullyes
customer.idstring (uuid)yes
customer.namestringyes

Lead

Fields
FieldTypeRequiredNotes
idstring (uuid)yes
namestringyes
emailstring | nullyes
phonestring | nullyes
notesstring | nullyes
status"new" | "contacted" | "quote_sent" | "won" | "lost"yes
source"whatsapp" | "voice" | "test" | "website" | nullyes
customer_idstring (uuid) | nullyes
project_idstring (uuid) | nullyes
external_referencestring | nullyes
created_atstringyes

Document

Fields
FieldTypeRequiredNotes
idstring (uuid)yes
numberstring | nullyes
type"quote" | "invoice"yes
invoice_kind"partial" | "final" | nullyes
status"draft" | "published" | "sent" | "accepted" | "rejected" | "lost" | "partially_paid" | "paid" | "cancelled"yes
datestring | nullyes
due_datestring | nullyes
currencystringyes
net_amountnumber | nullyes
tax_ratenumber | nullyes
tax_amountnumber | nullyes
gross_amountnumber | nullyes
customer_idstring (uuid) | nullyes
project_idstring (uuid) | nullyes
has_pdfbooleanyes
created_atstringyes
updated_atstring | nullyes

DocumentDetail

Fields
FieldTypeRequiredNotes
idstring (uuid)yes
numberstring | nullyes
type"quote" | "invoice"yes
invoice_kind"partial" | "final" | nullyes
status"draft" | "published" | "sent" | "accepted" | "rejected" | "lost" | "partially_paid" | "paid" | "cancelled"yes
datestring | nullyes
due_datestring | nullyes
currencystringyes
net_amountnumber | nullyes
tax_ratenumber | nullyes
tax_amountnumber | nullyes
gross_amountnumber | nullyes
customer_idstring (uuid) | nullyes
project_idstring (uuid) | nullyes
has_pdfbooleanyes
created_atstringyes
updated_atstring | nullyes
pdfobject | nullyes
pdf.urlstring (uri)yes
pdf.expires_atstringyes
pdf.requires_postal_codetrueyes

TimeEntry

Fields
FieldTypeRequiredNotes
idstring (uuid)yes
user_idstring (uuid) | nullyes
project_idstring (uuid)yes
datestringyes
start_timestring | nullyes
end_timestring | nullyes
break_minutesintegeryes
duration_minutesintegeryes
work_type"arbeiten" | "laden" | "fahren" | "pause"yes
descriptionstring | nullyes
is_billableboolean | nullyes
status"pending" | "approved" | "rejected" | "invoiced"yes
external_sourcestring | nullyes
external_idstring | nullyes
projectobject | nullyes
project.idstring (uuid)yes
project.namestringyes