Configuration Package Excel API
The Configuration Package Excel API enables any automation tool—such as PowerShell, Power Automate, custom scripts, or external systems—to import Excel-based configuration packages into Business Central programmatically, without requiring an interactive user session. This API is designed specifically for data migration scenarios and data migration automation, where configuration data is maintained in Excel workbooks. PowerShell is a common choice, but the API is not limited to any specific technology.
The Excel workbook must be in the official RapidStart (Configuration Package) format, exported from Business Central using the standard Export to Excel action on a Configuration Package. The worksheet structure encodes the package code and table mapping that Business Central expects on import. Arbitrary Excel or CSV files are not supported; only the official format is accepted by the API, matching Business Central's native capabilities.
Why only RapidStart Excel packages?
Business Central's APIs natively support only the import of "RapidStart" configuration packages (Excel files exported from Business Central’s Configuration Package feature). This API provides a supported, robust way to automate data migration and configuration loading using the same format, ensuring compatibility and reliability. Any tool capable of making HTTP requests and handling authentication can use this API to automate the process.
API Details
| Property | Value |
|---|---|
| Publisher | theta |
| Group | adminTools |
| Version | v1.0 |
| Entity (singular) | configPackageExcel |
| Entity (plural) | configPackagesExcel |
| Source table | Config. Package |
| Key | SystemId (GUID) |
Base URL pattern:
/api/theta/adminTool/v1.0/companies({companyId})/configPackagesExcel
Fields
| JSON property | Type | Editable | Description |
|---|---|---|---|
id | GUID | No | SystemId of the Config. Package record |
code | Code | Yes | Package code (e.g. MYPACKAGE) |
packageName | Text | Yes | Descriptive name of the package |
languageId | Integer | Yes | Language ID for the package |
productVersion | Text | Yes | Product version string |
processingOrder | Integer | Yes | Order in which this package is processed |
excludeConfigurationTables | Boolean | Yes | Whether to exclude configuration tables |
numberOfTables | Integer | No | Number of tables in the package |
numberOfRecords | Integer | No | Total number of records across all tables |
numberOfErrors | Integer | No | Number of validation errors |
importStatus | Option | No | Current import status (No, Scheduled, InProgress, Completed, Error) |
importError | Text | No | Error message from the last failed import |
applyStatus | Option | No | Current apply status (No, Scheduled, InProgress, Completed, Error) |
applyError | Text | No | Error message from the last failed apply |
Excel File Sub-endpoint
Each configuration package has a nested excelFile endpoint that holds the uploaded Excel workbook content. This maps to Business Central's Tenant Config. Package File table — the same storage used by the standard automation API.
| Property | Value |
|---|---|
| Entity (singular) | configPackageExcelFile |
| Entity (plural) | configPackageExcelFiles |
| Source table | Tenant Config. Package File |
| Key | code (package code) |
URL pattern:
/api/theta/adminTool/v1.0/companies({companyId})/configPackagesExcel({id})/configPackageExcelFiles
| JSON property | Type | Editable | Description |
|---|---|---|---|
code | Code | No | Package code — matches the parent record |
filecontent | BLOB | Yes | Binary content of the Excel workbook |
Import Workflow
The full workflow involves three API calls:
Step 1 — Look up the Config. Package
GET /api/theta/adminTool/v1.0/companies({companyId})/configPackagesExcel?$filter=code eq 'MYPACKAGE'
Authorization: Bearer {accessToken}
Note the id (SystemId GUID) from the response — you need it for subsequent calls.
Step 2 — Upload the Excel file
Upload the binary Excel content to the nested file endpoint. Use PATCH if a file already exists for this package code, or POST to create a new entry.
PATCH /api/theta/adminTool/v1.0/companies({companyId})/configPackagesExcel({id})/configPackageExcelFiles({code})
Authorization: Bearer {accessToken}
Content-Type: application/octet-stream
<binary .xlsx file content>
The package code (code) used as the file endpoint key must exactly match the Code stored in the Excel workbook's worksheets. If the codes do not match, the import will fail with a validation error from Business Central's Config. Excel Exchange engine.
Step 3 — Import the Excel data
Call the importExcel bound action. This reads the uploaded workbook from Tenant Config. Package File and populates the Config. Package data tables using Business Central's standard Excel exchange engine.
POST /api/theta/adminTool/v1.0/companies({companyId})/configPackagesExcel({id})/Microsoft.NAV.importExcel
Authorization: Bearer {accessToken}
Content-Type: application/json
{}
A 200 OK response (with or without a body) indicates success. Check importStatus and importError on the package record if you receive a 400 or 422.
Replace workflow behavior
The import process uses a replace workflow for an existing package code: the existing package content is deleted before the workbook is imported.
- If you re-import the same package ID, the previous package content is cleared first, so the latest file becomes the single source of truth.
- If you run automated imports repeatedly (for example from PowerShell or pipelines), each run starts from a clean package state to reduce carry-over issues.
- If an old package setup is causing inconsistent results, running a new import replaces it automatically instead of layering changes.
Step 4 — Apply the package
Call the applyPackage bound action. This applies all tables in the package to Business Central data using the standard Config. Package Management engine, which validates field mappings and writes records.
POST /api/theta/adminTool/v1.0/companies({companyId})/configPackagesExcel({id})/Microsoft.NAV.applyPackage
Authorization: Bearer {accessToken}
Content-Type: application/json
{}
Check applyStatus and applyError on the package record after calling this action to confirm the outcome.
Error Handling
| HTTP Status | Cause | Action |
|---|---|---|
400 Bad Request | No file uploaded for the package code, or file is empty | Upload the Excel file to the excelFile endpoint first |
400 Bad Request | Package code in the workbook does not match the record | Ensure the Excel file was exported from the correct package |
422 Unprocessable Entity | Business rule violation during apply (e.g. missing posting group) | Inspect applyError on the package record; fix the data in the workbook and re-import |
404 Not Found | Wrong company ID or package ID | Verify the companyId and the id returned from Step 1 |
Authentication
Access to this API requires a valid OAuth 2.0 bearer token. The API user or AAD app registration must have the Administration Tools - Super (SUPER_IMP_TSL) or Administration Tools - Basic (BASIC_IMP_TSL) permission set assigned in Business Central, in addition to standard Business Central permissions for Config. Package objects.