This is the synchronous interface for the Tracking API. Use it to record a flow controlled by an external application: create incoming interchanges and documents, attach files, and report progress or failures. Link provides tracking, logging, and configured error handling, including error rules.
Base path: /api/rest/operation/tracking. See [API conventions](api-conventions.md) for authentication and shared terms. For interface selection and the distinction from Async Flow, start with the External Flow Tracking APIs .
.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 Tracking role contains these permissions:
|
Operation group |
Permission |
|---|---|
|
Initiate single-document or interchange tracking |
|
|
Add a document to an existing incoming interchange |
|
|
Update document metadata or set its partners |
|
|
Set outgoing interchange |
|
|
Update interchange metadata |
|
|
Record status |
|
|
Attach primary tracked files |
|
|
Attach supplementary files |
|
|
Extract tracking fields from CDM |
|
Partner fields describe the tracked document; they do not establish an Inbox/Outbox-style boundary restricting the caller to its own partner. Grant tracking permissions to users intended to record the relevant environment's activity.
Call sequence
-
For one document, call
POST /initiate-single-document-tracking. It returnsinterchangeInanddocument, each with anentityId. -
For several documents in one incoming transmission, instead call
POST /initiate-interchange-tracking, retaininterchange.entityId, and callPOST /track-documentfor each document with that value asinterchangeId. -
Retain the returned numeric IDs. Attach any tracked files and record subsequent document status using the document ID.
-
If recording an outgoing transmission, call
POST /set-interchange-outwithdocumentIdand the outgoing interchange metadata/files before attaching files that require that outgoing relation.
Configured document type, format, variant, version, and partner-system names must match the target environment. Unknown names are not automatically created by this mapping flow. Partners are looked up first by known qualifier/value identifications, then by name. Unknown partners are not auto-created by this implementation, despite older operation descriptions suggesting otherwise.
Example: track an externally processed order
Assume the Order document type and Xml format type exist. Prepare tracking-start.json below. Replace the sample GUIDs with fresh GUIDs for each new transmission/document and persist those references with your integration's record.
{
"interchangeIn": {
"interchangeGuid": "3d25572a-78e8-4b09-bdb8-0a8f6fbef635",
"interchangeNumber": "ERP-2026-1001",
"fileName": "order-1001.xml",
"formatType": "Xml",
"transportDisplayName": "Contoso ERP"
},
"document": {
"documentGuid": "a9068344-4e4b-40b9-a441-ecc434149d37",
"documentNumber": "1001",
"documentTypeName": "Order"
},
"initialStatus": {
"statusName": "Inbox",
"source": "Contoso ERP",
"comment": "Accepted by the external integration"
},
"contextProperties": []
}
Create the record and retain its response:
set -euo pipefail
LINK_API_BASE='https://<your-link-api-host>'
LINK_PAT='<your-personal-access-token>'
curl --silent --show-error --fail-with-body \
--user ":${LINK_PAT}" --header 'Content-Type: application/json' \
--data-binary '@tracking-start.json' \
"${LINK_API_BASE}/api/rest/operation/tracking/initiate-single-document-tracking" \
--output tracking-created.json
DOCUMENT_ID=$(jq -er '.document.entityId' tracking-created.json)
After your application has successfully completed its processing, record that outcome:
jq -n --argjson id "${DOCUMENT_ID}" \
'{documentId:$id,status:{statusName:"Completed",source:"Contoso ERP",comment:"Order processed successfully"}}' \
> tracking-completed.json
curl --silent --show-error --fail-with-body --include \
--user ":${LINK_PAT}" --header 'Content-Type: application/json' \
--data-binary '@tracking-completed.json' \
"${LINK_API_BASE}/api/rest/operation/tracking/set-document-status"
Creation returns 200 with JSON. Setting status returns 204 with no body. Use agreed status names: a configured document status changes the lifecycle state, while a technical status records an event. Error handling rules can affect the resulting state when an exception is supplied. Setting Completed records your application's outcome; it does not execute or validate that work.
Files and updates
-
POST /track-filetakesdocumentIdandfile. The file includesfileName,base64FileData, andfileType, such asMessageInorMessageCdm. It can replace the corresponding file reference; it is not a raw-body upload. -
POST /track-additional-filetakes a supplementary file with its configuredadditionalFileTypeandadditionalFileRelation: Document, InterchangeIn, or InterchangeOut. It returns a file ID. Repeating it can create another attachment. -
POST /track-cdmextracts configured tracking fields from an existing MessageCdm file. Upload that file first and configure the document type's tracking-field XPaths. Without a document/CDM file this operation can do nothing and still return 204. -
PATCH /update-documentusesdocument.entityIdordocument.documentGuid; numeric ID takes precedence. Null mapped fields generally retain their current values. Include the existing GUID: omitting it can generate a new GUID during mapping. This is not a general JSON Patch operation. -
PATCH /update-interchange-inand/update-interchange-outrequireinterchange.entityId. Include the existing interchange GUID for the same reason. Use/set-partner-inand/set-partner-outfor explicit partner reassignment; an unresolved partner does not create one.
Tracking failures
Missing referenced records, invalid GUIDs, file decoding errors, and downstream validation can surface as 500, rather than a uniform 400/404 contract. Validate reference names and keep IDs from successful responses. A timeout after creation is an uncertain outcome; reconcile using the persisted GUID and Link records before creating again. There is no request-level deduplication guarantee, and retrying a status or file operation can repeat logs or attachments.