What you use the Crownbeam API for
The Crownbeam API lets other programs access your lab's data directly, without anyone clicking through Crownbeam. Labs use the API, for example, to connect their own invoicing software or to build reports on their production.
Through the API you can retrieve, among other things, the following data:
Orders
Order positions
Products
Customers
Locations
You take the data into a tool of your choice, for example Excel or Power BI. The connection itself is usually built by a developer. In Crownbeam, you need an API user with the right permissions for it, as described below.
What an API user is
An API user is a separate system user that external systems use to access the Crownbeam API. An API user is required for API access, a personal account cannot be used for it. You create the user yourself and give it exactly the permissions the connected system needs.
You find this area under Settings → My Data → API Management.
Note: API Management is marked as Beta.
How to create an API user
Open Settings using the gear icon in the top right corner.
Under My Data, select API Management.
In the API Users section, click Manage API Users.
Click Create Systemuser in the top right corner.
Enter a Name and use the Description field to record what the user is for.
Select the Language.
Click Create.
Tip: Create a separate API user for each connected system and name it accordingly. That way you can tell at a glance which access belongs to which system, and you can switch off a single connection without affecting the others.
Which permissions are available
The available permissions are listed in API Management under the Available permissions button. Crownbeam discovers this list automatically from the existing API endpoints.
The permissions are grouped by data area, for example Order, Files, Message and Location. Each area offers four actions:
Action | What it allows |
ADD | Create new entries |
CHANGE | Edit existing entries |
DELETE | Delete entries |
VIEW | Read entries |
Every permission comes with a name, a technical codename such as view_order and an ID. As a rule, only the developer who builds the connection needs these details.
Important: Only give an API user the permissions the connected system actually needs. A user that only reads data does not need DELETE.
The rights of your team are handled separately. You still assign them under Settings → My Business → Team, as described in Manage user permissions.
Which APIs are available
Crownbeam provides three REST APIs. Which one you need depends on the perspective the external system works from:
API | Purpose |
Admin API | Administrative tasks. No functions available yet. |
Lab API | Access from the lab perspective |
Practice API | Access from the practice perspective |
You open the overview in API Management using Visit API Portal. For each API you find the documentation, the schema and a Swagger interface for testing there, along with the supported authentication methods.
Note: If you need support implementing an integration, contact [email protected].
What the Lab API currently can't do
The Lab API doesn't cover everything you can do in the Crownbeam web interface. These limitations currently apply:
Inbox: Scans from DS Core, Medit or 3Shape Communicate that are still in the Inbox aren't orders yet and don't appear in the API. Only once you assign the scan to a practice in the Inbox and accept it can it be retrieved via the API. The Inbox itself can't be read via the API, and scans can't be accepted through it.
The positions of an order can't be changed via the API. Crownbeam calculates price and delivery time from the price list and the order settings.
Crownbeam doesn't notify your software of new orders or status changes on its own, there are no webhooks. Instead, your software retrieves the data at regular intervals.
Note: You'll find technical details such as request limits, filters and page sizes in the API documentation in the API Portal.
FAQs
Can I create an API user myself?
You can create an API user yourself. The path is Settings → My Data → API Management → Manage API Users, then Create Systemuser. You do not need to contact support for this.
Why do I need a separate user for the API?
A separate user is required for the API so that technical access runs independently of personal accounts. This lets you tailor the permissions to the connected system and switch the access off without changing an employee account.
Where do I find the API documentation?
The API documentation is available in the API Portal. You reach it under Settings → My Data → API Management using the Visit API Portal button.
Can I create reports on my production?
Crownbeam doesn't offer reports on your production in the portal, for example units produced per month by restoration type, material or practice. You get these figures via the API: you retrieve orders, order positions, products, customers and locations and analyze them in a tool of your choice. This also works for past months. The Crownbeam team doesn't create reports by hand.
Does Crownbeam notify my software about new orders?
Crownbeam currently doesn't actively notify your software about new orders or status changes, there are no webhooks. Instead, your software retrieves the data from the API at regular intervals. For most cases, every 5 minutes is enough. Each API user can make up to 120 requests per minute.
Why don't I see scanner orders via the API?
Scanner orders from DS Core, Medit or 3Shape Communicate only appear in the API once the scan has become an order. While a scan is in the Inbox, you assign it to a practice there and accept it. If you select the Automatically assign in the future checkbox, later scans from the same sender are created as orders right away and can be retrieved via the API immediately.
Is there a test account for the API?
To develop a connection, Crownbeam provides a test account on request. Contact Crownbeam support and give an email address to be linked to the test account. This address must not already be in use in Crownbeam.