Tracking API

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

API_Tracking_InitiateTracking

Add a document to an existing incoming interchange

API_Tracking_TrackDocument

Update document metadata or set its partners

API_Tracking_UpdateDocument

Set outgoing interchange

API_Tracking_SetInterchangeOut

Update interchange metadata

API_Tracking_UpdateInterchange

Record status

API_Tracking_SetDocumentStatus

Attach primary tracked files

API_Tracking_TrackFile

Attach supplementary files

API_Tracking_TrackAdditionalFile

Extract tracking fields from CDM

API_Tracking_TrackCdm

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

  1. For one document, call POST /initiate-single-document-tracking. It returns interchangeIn and document, each with an entityId.

  2. For several documents in one incoming transmission, instead call POST /initiate-interchange-tracking, retain interchange.entityId, and call POST /track-document for each document with that value as interchangeId.

  3. Retain the returned numeric IDs. Attach any tracked files and record subsequent document status using the document ID.

  4. If recording an outgoing transmission, call POST /set-interchange-out with documentId and 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.

JSON
{
  "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-file takes documentId and file. The file includes fileName, base64FileData, and fileType, such as MessageIn or MessageCdm. It can replace the corresponding file reference; it is not a raw-body upload.

  • POST /track-additional-file takes a supplementary file with its configured additionalFileType and additionalFileRelation: Document, InterchangeIn, or InterchangeOut. It returns a file ID. Repeating it can create another attachment.

  • POST /track-cdm extracts 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-document uses document.entityId or document.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-in and /update-interchange-out require interchange.entityId. Include the existing interchange GUID for the same reason. Use /set-partner-in and /set-partner-out for 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.