Customer API

Grunddata also provides a rich customer API for IT teams, integrations and automated workflows. The web app, Excel plugin and Google Sheets add-on use this same API, so an integration built against it follows the same authentication, validation, commits and versioning rules as the user interfaces.

Which interface should I use?

• OData is the right choice for read-only consumption in Excel, Power Query and Power BI.
• The customer API is the right choice for applications, ETL jobs and automation that need to create or update models, tables, attributes, views or records.
• The web app and plugins are the right choice for people doing the work manually.

API documentation

The API is built with FastAPI and publishes interactive documentation for each customer environment:

Resource	URL
Swagger UI	<customer-api-base-url>/docs
ReDoc	<customer-api-base-url>/redoc
OpenAPI schema	<customer-api-base-url>/openapi.json

Replace <customer-api-base-url> with the customer API host supplied by your Grunddata administrator. Depending on the deployment’s reverse proxy, this may include an /api prefix. For example:

https://<customer-api-host>/api/docs
https://<customer-api-host>/api/openapi.json

Swagger UI is not a separate API

Swagger UI and ReDoc are views of the live OpenAPI contract. They do not create another service, and they do not bypass authentication. Use the OpenAPI schema to generate a client only after confirming the version and deployment URL with your administrator.

Using Swagger UI

1. Open the customer API’s /docs URL.

2. Find the operation you want. The operations are grouped by domain, such as models, tables, attributes, records, views, tags and authentication.

3. Click Try it out.

4. Fill in the path parameters and request body shown by the schema.

5. Click Execute. Swagger UI shows the request URL, response status and response body.

The customer API routes are protected by the same tenant and user authentication used by the web app. A request must be made in the context of the correct customer environment.

Treat the API documentation as customer-specific

The endpoint shapes are shared by the product, but the data and available operations depend on the customer environment and the signed-in user’s access. Do not copy a URL from one environment into another.

What the API can do

The API includes operations for:

Area	Examples
Models	List, create, update and delete models
Tables	List, create, update and delete tables; inspect the table overview; create initial attributes and Excel formulas atomically
Attributes	List and manage datatypes, required/unique settings, domain references, validation schemas and formulas
Records	Read records, create and update records in batches, delete records, validate rules
Views	Create, update, list and delete stable OData contracts
Tags	List and manage catalogue labels used for filtering and access control
OData	Read configured views using the OData protocol

The exact request and response models, required fields and allowed operations are always defined by the live Swagger UI and OpenAPI schema.

Creating structure from a spreadsheet

The Excel plugin can create a new table, its initial attributes and any Excel formulas as one unit before it uploads rows. If any part of the structure is invalid, none of it is created. The plugin then uses the returned permanent identifiers when it uploads records.

Swagger is the source for endpoint details

The API grows with the product. Use the live Swagger UI or OpenAPI schema for route names, request bodies and response fields rather than copying endpoint details from this overview.

The same rules as the UI

Using the API does not create a way around governance:

• Required and unique attributes are enforced.
• Datatypes, max length, precision and scale are enforced.
• Domain attributes must resolve to records in the referenced domain table.
• Attribute and table validation rules are enforced.
• Record writes produce commits and versions.
• Failed writes are returned through record audit information and do not partially save the failing record.

Use commit messages in automation

Batch record updates accept a commit message. Make it descriptive and include the source of the change, for example Nightly ERP account synchronisation or Import approved counterparties 2026-08-14.

API or OData?

Use the following decision guide:

Need	Recommended interface
Build a Power BI model	OData
Refresh a read-only Excel report	OData
Load data into an ETL pipeline	OData for reads; customer API for writes
Create a new model or table automatically	Customer API
Synchronise records from another system	Customer API batch record operations
Let a person maintain records	Excel plugin or Google Sheets add-on
Explore and test a request manually	Swagger UI at /docs

Do not use OData for writes

The OData surface is read-only. Use the customer API or one of the plugins to create, update or delete records.

API access and support

Ask your Grunddata administrator for:

1. The customer API base URL for the environment you need.
2. The Microsoft Entra application and delegated scope used by your integration.
3. The tenant and group access required for the models and tables involved.
4. Any deployment-specific /api prefix used by the reverse proxy.

Do not put client secrets in a spreadsheet, script shared with end users, or frontend code. Use your organisation’s approved secret store and service-to-service authentication pattern.

OData APIConnect Excel, Power Query and Power BI to read-only views.

RecordsUnderstand the data model before writing records.

Commits and versionsHow API writes are recorded and versioned.