Configuration Import API

Apply a Link configuration export through the REST API. The areas are Partner, Distribution, and Developer. The workflow is compare, review, then import.

Base path: /api/rest/operation/import. Obtain the export through Link's configuration export tools. This page covers configuration imports only. Authentication and common request conventions are in API Conventions .

.NET clients

For .NET clients, we recommend using the Bizbrains.Link.Api.Proxy NuGet package. See .NET client library for the public NuGet feed, supported APIs, and shared guidance.

Permissions

The API Import role groups these permissions:

Area

Compare and import paths

Permission

Partner

/compare-partner, /import-partner

API_Import_Partner

Distribution

/compare-distribution, /import-distribution

API_Import_Distribution

Developer

/compare-developer, /import-developer

API_Import_Developer

An export containing artifacts additionally requires API Import Artifacts (API_Import_Artifacts). Without it, comparison reports readyToImport: false, and an import containing artifacts is rejected with 403.

The route grants access by configuration area, not by a partner-selection request parameter. Exports can contain referenced shared configuration. Review all returned item groups and changes before importing.

Compare and review

POST JSON containing base64EncodedFileString: the base64-encoded export file bytes. The response contains:

  • importCompareResult: the comparison and proposed item/property changes.

  • readyToImport: whether the comparison is ready and the artifact permission check passed.

Inspect additions, updates, deletions, missing references, and blocked items. Resolve blockers and compare again. A false readiness flag can also mean a missing permission, not only invalid configuration.

The compare phase does not commit the proposed import. It is also not a lock on destination configuration. Compare again if the destination changed after review. The REST comparison in this implementation bypasses the export's Link-version mismatch check, so readiness is not proof of cross-version compatibility.

Example: Partner configuration

With Bash, curl, base64, and jq, compare the file exported from Link:

Bash
set -euo pipefail
LINK_API_BASE='https://<your-link-api-host>'
LINK_PAT='<your-personal-access-token>'

base64 < partner-export.xml | tr -d '\r\n' \
  | jq -Rs '{base64EncodedFileString:.}' > compare-request.json

curl --silent --show-error --fail-with-body \
  --user ":${LINK_PAT}" --header 'Content-Type: application/json' \
  --data-binary '@compare-request.json' \
  "${LINK_API_BASE}/api/rest/operation/import/compare-partner" \
  --output compare-response.json

jq '{readyToImport,importCompareResult}' compare-response.json

Review the response before proceeding. Preserve the returned comparison object; do not reconstruct it from displayed fields. Once the proposed changes have been accepted:

jq -e '.readyToImport == true' compare-response.json > /dev/null
jq '{importData:.importCompareResult}' compare-response.json > import-request.json

curl --silent --show-error --fail-with-body --include \
  --user ":${LINK_PAT}" --header 'Content-Type: application/json' \
  --data-binary '@import-request.json' \
  "${LINK_API_BASE}/api/rest/operation/import/import-partner"

Successful comparison returns 200 with JSON. Successful import returns 200 with an empty body. For Distribution or Developer, use that area's corresponding pair of paths.

Import effects and failures

Import resolves object dependencies and applies the returned comparison, including its selected changes and supported deletions. It can also ensure EDI configuration exists for imported partners. The import's database changes run within a transaction; blocked items are rejected before execution. This is not a request to process business documents.

Invalid export bytes, incompatible structures, unresolved references, blocked imports, and persistence errors can surface as 500. Treat readyToImport: true as the prerequisite for submission; the import action does not perform a fresh comparison or reproduce every readiness check.

After a timeout, inspect destination configuration before submitting again. Retrying an old comparison is not an idempotent replay contract, and it may no longer reflect the destination. Compare a fresh export against the current destination and review the new result before another import.