MDM API Reference

Use this page as an implementation map for DFS MDM APIs. Keep the deployment's live API specification as the source for exact request and response fields.

Access assumptions

Confirm:

• authentication method;
• tenant scope;
• dfs:read for viewing MDM records;
• dfs:write for creating or updating records and review decisions;
• dfs:delete only for structural actions such as merge and split;
• DFS Pro package access where required by the deployment.

Request conventions

Use the deployment's live OpenAPI or API console for exact schemas. For implementation planning, align on these conventions before writing an integration:

Convention	Guidance
Tenant scope	Every read and write should execute inside the intended tenant or project boundary.
Source system key	Use stable domain keys such as bms, cmms, or inspection so integrations share the same namespace.
External ID	Preserve the source system's durable ID so aliases can be resolved repeatedly.
Idempotency	Use deterministic keys for reference sets, entity types, and source aliases so retries do not create duplicates.
Audit reason	Include a requester, reason, or change note for structural writes when the deployment supports it.
Time validity	Send valid-from and valid-to values when source IDs can be reused or equipment can be replaced.

For list endpoints, plan for paging and filtering by entity type, status, source system, updated time, and steward decision state. Large integrations should read incrementally instead of polling the entire MDM store.

Reference data APIs

Area	Endpoint family	Use
Reference sets	/api/v1/dfslite/mdm/reference-sets	List and create reference sets.
Reference set detail	/api/v1/dfslite/mdm/reference-sets/{key}	Read a set by key.
Version bump	/api/v1/dfslite/mdm/reference-sets/{key}/bump-version	Increment version after a meaningful change.
Values	/api/v1/dfslite/mdm/reference-sets/{key}/values	List and add values.
Value detail	/api/v1/dfslite/mdm/reference-sets/{key}/values/{valueId}	Update or delete one value.

Entity and alias APIs

Area	Endpoint family	Use
Entity types	/api/v1/dfslite/mdm/entity-types	List or create master entity types.
Entity type detail	/api/v1/dfslite/mdm/entity-types/{typeKey}	Read one entity type.
Entities	/api/v1/dfslite/mdm/entities	List or create golden records.
Entity detail	/api/v1/dfslite/mdm/entities/{id}	Read one golden record.
Aliases	/api/v1/dfslite/mdm/entities/{id}/aliases	List source aliases for a golden record.
Resolve	/api/v1/dfslite/mdm/xref/resolve	Resolve a source-system ID to an entity ID.
Upsert alias	/api/v1/dfslite/mdm/xref	Create or re-point a source alias.

Safe alias writes

Before writing aliases automatically:

1. Resolve the source-system ID first.
2. Check whether the active mapping already points to the expected entity.
3. Use the approved re-point workflow for conflicting mappings.
4. Preserve the old mapping history when an alias changes because an asset was replaced, split, or merged.
5. Revalidate downstream datasets that join on the master entity ID.

Integrations should treat alias writes as governed identity changes. Do not use alias upsert as a generic data-cleaning shortcut.

Steward APIs

Area	Endpoint family	Use
Fuzzy candidates	/api/v1/dfslite/mdm/fuzzy-candidates	List steward candidates by type and status.
Approve candidate	/api/v1/dfslite/mdm/fuzzy-candidates/{id}/approve	Confirm a candidate and create the alias.
Reject candidate	/api/v1/dfslite/mdm/fuzzy-candidates/{id}/reject	Reject a candidate and record the negative decision.
Merge	/api/v1/dfslite/mdm/entities/{loserId}/merge-into/{survivorId}	Merge a duplicate entity into the survivor.
Split	/api/v1/dfslite/mdm/entities/{entityId}/split	Move selected source aliases into a new entity.

Steward automation boundaries

Automation can list candidates, pre-filter queues, and attach evidence for reviewers. Approval and rejection should follow the deployment governance policy. For high-impact entity types, keep a human decision step and record enough evidence for audit.

For candidate lists, use filters such as entity type, status, source system, score range, created time, and updated time when available. This keeps review tools responsive and avoids mixing unrelated entity types in one steward queue.

Integration checklist

Before automating MDM:

• use stable source-system names;
• use domain-based entity type keys that remain stable across environments;
• validate reference sets before entity resolution;
• test with a small source slice;
• confirm the steward queue owner;
• log every write action with requester, reason, and downstream impact;
• route fuzzy matches through steward review;
• revalidate downstream fusion and reporting after structural actions.
• retry read operations safely, but review write retries for idempotency;
• alert on repeated alias conflicts or a sudden increase in fuzzy candidates;
• include run IDs or task names when MDM output feeds AI Agent, Inspector, BI, or work-order integrations.

Error patterns

Symptom	Likely cause	Fix
403 or hidden action	Missing permission or package gate.	Confirm dfs:read, dfs:write, dfs:delete, and DFS Pro access.
Unknown entity type	Entity type was not created in the tenant.	Create or select the correct type before writing entities or aliases.
Alias conflict	The source ID already has an active mapping.	Re-point through the approved workflow or close the old mapping.
Empty steward queue	No resolver candidates, wrong entity type filter, or no fuzzy matches created.	Check resolver run results and filters.
Merge blocked	Target or source entity is invalid for structural change.	Confirm both records exist, are in the same tenant, and have the expected status.
Duplicate entity growth	Source keys are unstable or deterministic matching is too weak.	Review source mappings, required fields, and resolver configuration before rerunning.
Repeated false candidates	Rejected-pair memory is missing from the resolver context.	Include previous steward decisions in the next resolver run.
Downstream report changes unexpectedly	Alias, merge, or split changed the master entity ID used by a fusion task.	Compare pre-change and post-change row movement and refresh only after review.

Response handling

For production integrations:

• treat 4xx responses as configuration, permission, validation, or governance issues that need review;
• treat 5xx responses as transient service or dependency failures and retry with backoff when the request is safe to retry;
• retry structural writes only after checking whether the first attempt committed;
• write client logs with request ID, tenant, endpoint family, entity type, source system, and operation result;
• expose retry and failure counts to the operations team during onboarding.

Next step

Use DFS API Surface for the wider DFS endpoint map.