1. Target Picture
The integration connects an external source system to the Public REST API in order to synchronize asset-related master data.
The basic data flow is:
Customer External source system
→ Customer Integration component / middleware
→ caralegal Public REST API
The external source system remains the leading system for the synchronized master data. Caralegal receives this information as assets and uses it within privacy, compliance, and governance processes.
Additional source systems may be connected later, but they are not part of the initial integration scope.
2. Responsibilities
The Public REST API provides endpoints to read, create, and update assets and reference data.
Public REST API Openapi documentation link : https://public-api.caralegal.de/swagger/#/
Get the documentation login and password from your caralegal CS / Tech-Support.
The implementation of the synchronization logic or middleware is outside the responsibility of caralegal. The integration owner or implementation partner is responsible for:
retrieving relevant data from the source system
mapping source data to the asset model
detecting new or changed records
calling the Public REST API
handling errors and retries
defining synchronization intervals
handling deactivated or removed source-system records
3. Asset Identification via externalId
Each object imported from the source system should store the stable source-system identifier as externalId.
Example:
{
"name": "SAP HCM",
"externalId": "source-12345"
}
The externalId acts as the unique technical reference between the source system and the target application.
Recommended approach:
The source system provides an object with a stable identifier.
This identifier is stored as externalId.
If the asset does not exist yet, it is created.
If the asset already exists, it is updated.
This prevents duplicates and keeps existing links in the target application intact. Existing assets should generally be updated instead of deleted and recreated.
4. Using externalId in API Calls
The externalId can also be used directly in REST API calls by using the ext:: prefix.
Examples:
GET /api/assets/ext::source-12345
PATCH /api/assets/ext::source-12345
DELETE /api/assets/ext::source-12345
This means the integration does not need to store internal target-system IDs.
Recommended approach:
Store the stable source-system ID as externalId.
Perform follow-up operations via ext::<externalId>.
Avoid storing internal UUIDs unless explicitly required.
The same principle can be used for other object types that support externalId, such as:
organizational units
resources
data locations
external recipients
5. Partial Updates and Data Ownership
The Public REST API supports partial updates using PATCH.
Only the fields that should be changed need to be sent.
Example:
{
"name": "SAP HCM Cloud",
"lastSyncedAt": "2026-08-19T10:00:00.000Z"
}
All attributes not included in the request remain unchanged.
This allows master data from the source system to be synchronized while privacy- or compliance-specific information continues to be maintained directly in the target application.
Example ownership model:
Source system maintains:
name
description
status
asset type
organizational unit
asset owner
Target application maintains:
processing activities
risks
technical and organizational measures
privacy information
compliance links
6. Manual Changes
For every synchronized field, it should be clearly defined which system is authoritative.
For example, if the asset name is synchronized from the source system, a manual change to that name in the target application may be overwritten during the next synchronization run.
Fields maintained exclusively in the target application are not affected, as they are not updated by the middleware.
7. lastSyncedAt
Each successful create or update operation can include lastSyncedAt.
Example:
{
"lastSyncedAt": "2026-08-19T10:00:00.000Z"
}
This field documents the timestamp of the last successful synchronization and supports:
traceability
support
error analysis
monitoring of the synchronization process
Delta detection and timestamp is handled by the integration component.
8. Labels
Assets can be categorized using labelIds.
Example labels:
SOURCE_SYSTEM
IMPORTED_FROM_EXTERNAL_SOURCE
TO_BE_REVIEWED
MIGRATION_PHASE_1
Labels support classification, filtering, and traceability. Technical asset identification should still rely on externalId.
9. Example Asset Request
{
"name": "SAP HCM",
"status": "ACTIVE",
"externalId": "source-12345",
"lastSyncedAt": "2026-08-19T10:00:00.000Z",
"resourceAssetTypeId": "...",
"assetOwnerId": "...",
"riskOwnerId": "...",
"mainOrgUnitId": "...",
"orgUnitIds": ["..."],
"labelIds": ["..."],
"dataLocationIds": ["..."],
"externalRecipientIds": ["..."]
}
Not all fields need to be used in the initial integration phase. The concrete mapping depends on the information available in the source system and the intended integration scope.
10. Relevant API Endpoints
Assets:
/api/assets
Users:
/api/users
Used for:
assetOwnerId
riskOwnerId
Organizational units:
/api/org-units
Used for:
mainOrgUnitId
orgUnitIds
Labels:
/api/resources/label
Asset types:
/api/resources/asset-type
Data locations:
/api/data-locations
External recipients:
/api/external-recipients
Additional reference data is generally available via:
/api/resources
/api/resources/{resourceType}
Risks and measures are not available through the Public API depending on the current API scope.
11. Authentication
For technical integrations, a refresh token can be provided and used as a Bearer token for API calls.
Example:
Authorization: Bearer <refresh-token>
Content-Type: application/json
Accept: application/json
The refresh token is intended for long-term use within the integration and should be stored securely, for example in a secret management system.
Alternatively, an access-token flow can be used if this better fits the integration architecture. In that case, an access token is generated based on the refresh token & client credentials and then used for API calls.
12. Create and Update
New assets are created through the API.
After a successful create operation, the newly created internal resource ID may be returned in the x-resource-id HTTP header.
However, the integration does not need to store this internal ID permanently. The recommended approach is to use the source-system identifier as externalId.
Existing assets are updated using PATCH. Since partial updates are supported, only the fields that should actually change need to be included. Existing links and attributes not included in the request remain unchanged.
13. Paging
Many GET endpoints support cursor-based paging.
Example:
GET /api/assets?limit=100
Typical response:
{
"items": [],
"cursors": {
"current": null,
"next": "..."
}
}
If cursors.next is present, the next page is loaded as follows:
GET /api/assets?limit=100&cursor=<next>
This process is repeated until no further cursor is returned.
For some endpoints, the result list name may differ, for example users instead of items.
Summary
The integration uses an external source system as the leading system for selected asset master data.
The Public REST API supports:
stable identification via externalId
direct API access via ext::<externalId>
partial updates using PATCH
asset classification through labels
synchronization tracking via lastSyncedAt
authentication via refresh token or access-token flow
The synchronization logic, mapping, operation, monitoring, and error handling are implemented by the integration owner or implementation partner.
This approach keeps the integration lightweight, avoids the need to persist internal target-system IDs, and preserves existing privacy and compliance links when asset master data is updated.