Retrieve Data Exchanges
Once a Data Exchange is created, it gets hosted on a hosting provider, such as Forma Data Management. To retrieve a Data Exchange, you need its Exchange Identifier/URN.
Handle Exchange Validation
In collaborative environments, exchanges may become inaccessible while you’re working—team members might restrict access, delete exchanges, or network issues may occur. This version of the SDK, unlike prior versions, lets you retrieve and work with all accessible exchanges even when some have problems.
Instead of failing completely when encountering an inaccessible exchange, the SDK returns your complete list of exchanges with a status indicator for each one. You can process the accessible exchanges immediately while handling problematic ones appropriately—whether that means showing a permission message, removing deleted items from your cache, or retrying failed requests.
Check validation status
The GetValidExchangesAsync method returns a collection of exchanges with their validation status. Each exchange includes a ValidationStatus property with the following information:
| Property | Type | Description |
|---|---|---|
StatusCode |
int | HTTP status code indicating the validation result |
ResponseMessage |
string | Detailed error message or description |
IsSuccess |
bool | true if the exchange is accessible (status code 200) |
IsUnauthorized |
bool | true if access is denied (status code 403) |
IsDeleted |
bool | true if the exchange no longer exists (status code 404) |
IsError |
bool | true for other errors (network issues, service unavailable) |
Common status codes:
200: Exchange is valid and accessible403: Insufficient permissions to access the exchange404: Exchange has been deleted- Other codes: Network errors, service unavailable, or other transient issues
Important: Always check
ValidationStatus.IsSuccessbefore attempting to load exchange data. Attempting to load exchanges with validation errors will fail.
Filter accessible exchanges
Use the ValidationStatus properties to identify which exchanges can be loaded:
var exchanges = await GetValidExchangesAsync();
// Get only accessible exchanges
var validExchanges = exchanges
.Where(e => e.ValidationStatus.IsSuccess)
.ToList();
Console.WriteLine($"Found {validExchanges.Count} accessible exchanges out of {exchanges.Count} total");
Handle validation errors
Check the validation status and respond appropriately:
foreach (var exchange in exchanges)
{
if (exchange.ValidationStatus.IsSuccess)
{
// Exchange is accessible - proceed with loading
var exchangeData = await Client.GetExchangeDataAsync(exchange.Identifier);
// Process the exchange data
}
else if (exchange.ValidationStatus.IsUnauthorized)
{
// User lacks permission - notify or disable actions
LogWarning($"Access denied to exchange '{exchange.Name}': {exchange.ValidationStatus.ResponseMessage}");
}
else if (exchange.ValidationStatus.IsDeleted)
{
// Exchange no longer exists - remove from local cache
LogInfo($"Exchange '{exchange.Name}' has been deleted");
}
else
{
// Other errors (network, service issues) - log for troubleshooting
LogError($"Cannot access exchange '{exchange.Name}': {exchange.ValidationStatus.ResponseMessage}");
}
}
Display validation errors
Build user-friendly messages based on the validation status:
var inaccessibleExchanges = exchanges.Where(e => !e.ValidationStatus.IsSuccess);
foreach (var exchange in inaccessibleExchanges)
{
string message = exchange.ValidationStatus.StatusCode switch
{
403 => $"You don't have permission to access '{exchange.Name}'",
404 => $"'{exchange.Name}' has been deleted",
_ => $"Cannot access '{exchange.Name}': {exchange.ValidationStatus.ResponseMessage}"
};
// Display the message in your UI
}
Recommendation: For permission errors, show the exchange in your UI with disabled actions rather than hiding it completely. This helps users understand what exchanges exist and why they cannot access them.
The Data Exchange Identifier
Identify Exchange to load
Exchanges are hosted on a hosting provider, such as Forma Data Management. Each exchange is assigned a unique identifier by its hosting provider. On Forma Data Management, this identifier is referred to as “entityId”. It can be extracted from the decoded URL of the exchange.
https://acc.autodesk.com/docs/files/projects/b.e3be8c87-1df5-470f-9214-1b6cc85452fa?folderUrn=urn%3Aadsk.wipprod%3Afs.folder%3Aco._BNKwsk-RZqkVuVAuuYjQA&entityId=`urn%3Aadsk.wipprod%3Adm.lineage%3A30m0VGWxR6CehOCs9TLcTQ`&viewModel=detail&moduleId=folders
Let’s break down the above URL to understand the other values that can be extracted:
- ProjectURN: b.e3be8c87-1df5-470f-9214-1b6cc85452fa
- folderURN: urn%3Aadsk.wipprod%3Afs.folder%3Aco._BNKwsk-RZqkVuVAuuYjQA&
- entityId: urn%3Aadsk.wipprod%3Adm.lineage%3A30m0VGWxR6CehOCs9TLcTQ
Retrieving the Data Exchange Identifier
The Data Exchange service assigns its own identifier to each Data Exchange, which is a combination of the CollectionId, ExchangeId, and HubId. To retrieve this identifier, the SDK provides an API that accepts the inputs “exchangeUrn” and “collectionId.” In this case, the “exchangeUrn” is the entityId (Note: Please use the decoded value) extracted from the URL mentioned above.
The CollectionId can be retrieved using the GetCollectionIdAsync method available on the IClient interface, which accepts ProjectURN (extracted from the URL above) as an input parameter and HubId as an optional parameter. The API returns a unique identifier object specific to the Data Exchange.
var collectionId = await Client.GetCollectionIdAsync("b.e3be8c87-1df5-470f-9214-1b6cc85452fa");
var ExchangeDetails = await Client.GetExchangeDetailsAsync(collectionId,"urn:adsk.wipprod:dm.lineage:30m0VGWxR6CehOCs9TLcTQ").ConfigureAwait(false);
var ExchangeIdentifier = new DataExchangeIdentifier
{
CollectionId = ExchangeDetails.CollectionID,
ExchangeId = ExchangeDetails.ExchangeID,
HubId = ExchangeDetails.HubId
};
The ExchangeIdentifier variable can now be used as an input to the GetExchangeDataAsync, GetExchangeRevisionsAsync, and SyncExchangeDataAsync methods.
Fetching an Exchange’s data
The GetExchangeDataAsync method returns the ExchangeData object, which is the client-side low-level data model for exchanges. The data returned represents the latest revision of the exchange at the time of retrieval.
ExchangeData ExchangeData = await Client.GetExchangeDataAsync(ExchangeIdentifier);
The ElementDataModel.Create method provides a high-level abstraction of the Data Exchange data model.
ElementDataModel Model = ElementDataModel.Create(Client, ExchangeData);
Exchange load progress
The SDK reports progress during exchange load operations in three stages. Each stage updates progress as work completes.

Stage 1: Fetch exchange details
Connectors define the substeps for this stage by implementing the GetLatestExchangeDataAsync method override. The SDK updates progress after each API call completes.
Example implementation:
var collectionId = (await this.Client.GetCollectionIdAsync(exchangeItem.ProjectURN, exchangeItem.HubId)).Value;
fetchExchangeStep.UpdateProgress();
var exchangeDetails = (await this.Client.GetExchangeDetailsAsync(collectionId, exchangeItem.FileURN)).Value;
fetchExchangeStep.UpdateProgress();
var revisions = (await this.Client.GetExchangeRevisionsAsync(exchangeIdentifier)).Value;
fetchExchangeStep.MarkAsComplete();
If you make three API calls, each call updates progress by 33% when it completes.
Stage 2: Download exchange data
The SDK completes these substeps:
- Fetches exchange metadata
- Downloads binary packs (count varies by exchange size)
- Parses binary packs into individual geometries
- Converts internal geometries to standard formats (STEP, MESH, OBJ)
Progress updates after each substep completes.
Example: An exchange with seven binary packs processes ten total substeps (metadata fetch + 7 binary pack downloads + parsing + conversion). Each substep updates progress by 10%.
Note: The DownloadCompleteExchangeAsSTEP, DownloadCompleteExchangeAsOBJ, and DownloadCompleteExchangeAsIFC methods don’t support progress reporting. Use an indeterminate progress indicator for these methods.
Opt out of download progress for a geometry call
During Stage 2, geometry-retrieval methods such as GetGeometriesAsync and GetElementGeometriesAsync can drive the SDK’s built-in download progress step. That is the default behavior.
If your connector already reports progress for a larger host operation, set ReportDownloadProgress to false on the GeometryOutputOptions for that call. The SDK skips download progress updates for that call only. Returned geometries, formats, and filters are unchanged.
var options = new GeometryOutputOptions { ReportDownloadProgress = false };
var geometries = await elementDataModel.GetElementGeometriesAsync(
elements,
cancellationToken,
options);
Note: ReportDownloadProgress applies per call. Do not overlap geometry-retrieval calls on the same ElementDataModel instance with different values for this property. Serialize those calls or use separate model instances.
Stage 3: Load exchange
In this stage, connectors load the downloaded geometry into their host application. Progress reporting depends on the connector implementation.
Retrieve the latest revision of a Data Exchange
You can call the GetExchangeRevisionsAsync method on the IClient interface, to retrieve a collection of revisions of the exchange. The revisions are sorted in chronological order starting from the most recent revision to the oldest. This method requires an instance of DataExchangeIdentifier as an input.
var ExchangeIdentifier = new DataExchangeIdentifier
{
CollectionId = ContainerID,
ExchangeId = ExchangeID,
HubId = HubId
};
//Get a list of all revisions
var Revisions = await Client.GetExchangeRevisionsAsync(ExchangeIdentifier);
var NewRevision = await Client.RetrieveLatestExchangeDataAsync(ElementDataModel);
var NewerRevisions = new List<string>();
if (!string.IsNullOrEmpty(NewRevision))
{
foreach (var Revision in Revisions)
{
if (Revision.Id == CurrentRevision)
{
break;
}
NewerRevisions.Add(revision.Id);
}
CurrentRevision = NewRevision;
}
Download complete exchange as OBJ
The SDK provides the DownloadCompleteExchangeAsOBJ method to download an entire exchange as OBJ geometry. Unlike the single-file STEP and IFC exports, this method returns the path to a folder, because an OBJ export produces an .obj file together with its .mtl material file. Use it when your host application consumes mesh geometry.
Method Signature:
IResponse<string> DownloadCompleteExchangeAsOBJ(
DataExchangeIdentifier dataExchangeIdentifier,
string objFolderPath = null,
CancellationToken cancellationToken = default)
Parameters:
dataExchangeIdentifier: The exchange identifier (contains ExchangeId, CollectionId, and HubId)objFolderPath(optional): Custom folder where the OBJ and MTL files are saved. If not provided, the SDK generates a default path.cancellationToken(optional): Token to cancel the download operation
Returns: Folder path containing the downloaded OBJ and MTL files
Note: This method does not support progress reporting. Use an indeterminate progress indicator when calling this method.
Changed in 8.0.0: This method takes a
DataExchangeIdentifier. Earlier versions took the exchange ID and collection ID as two separate strings, in that order. See Download as OBJ takes a DataExchangeIdentifier in the migration guide.
Example:
Use the exchange identifier obtained from Retrieving the Data Exchange Identifier section above.
// Using the ExchangeIdentifier from earlier in this tutorial
var result = Client.DownloadCompleteExchangeAsOBJ(ExchangeIdentifier);
if (result.IsSuccess)
{
Console.WriteLine($"OBJ output written to: {result.Value}");
}
// Specify exact location for OBJ export
var customFolder = @"C:\exports\my-building-obj";
var customResult = Client.DownloadCompleteExchangeAsOBJ(ExchangeIdentifier, customFolder);
if (customResult.IsSuccess)
{
Console.WriteLine($"OBJ output written to: {customResult.Value}");
}
If the identifier’s CollectionId is null, the call fails and IsSuccess is false. Check the result rather than assuming the download succeeded.
Download Complete Exchange as IFC
The SDK provides the DownloadCompleteExchangeAsIFC method to download an entire exchange as an IFC (Industry Foundation Classes) file. This method downloads all geometry from the exchange and exports it in the standard IFC format. Use this method to export exchanges for compatibility with BIM applications like Revit, ArchiCAD, or other IFC-compatible tools.
Method Signature:
IResponse<string> DownloadCompleteExchangeAsIFC(
DataExchangeIdentifier dataExchangeIdentifier,
string ifcFilePath = null,
CancellationToken cancellationToken = default)
Parameters:
dataExchangeIdentifier: The exchange identifier (contains ExchangeId, CollectionId, and HubId)ifcFilePath(optional): Custom path where the IFC file should be saved. If not provided, the SDK generates a default path.cancellationToken(optional): Token to cancel the download operation
Returns: File path to the downloaded IFC file
Note: This method does not support progress reporting. Use an indeterminate progress indicator when calling this method.
Example:
Use the exchange identifier obtained from Retrieving the Data Exchange Identifier section above.
// Using the ExchangeIdentifier from earlier in this tutorial
var result = Client.DownloadCompleteExchangeAsIFC(ExchangeIdentifier);
if (result.IsSuccess)
{
Console.WriteLine($"IFC file downloaded to: {result.Value}");
}
// Specify exact location for IFC export
var customPath = @"C:\exports\my-building.ifc";
var customResult = Client.DownloadCompleteExchangeAsIFC(ExchangeIdentifier, customPath);
if (customResult.IsSuccess)
{
Console.WriteLine($"IFC file saved to: {customResult.Value}");
}
Retrieve Parameters and ParameterSet of Elements
Each Element of the Data Exchange contains the following collection properties:
- InstanceParameters
- TypeParameters (For Revit type parameters only)
Type parameters apply to every instance of a particular family type and are used to define properties that are common across all instances of that type. Changes to type parameters affect all instances of that type within the project. These parameters are useful for properties that should be consistent across multiple instances, such as material, dimensions, or other characteristics that do not vary from one instance to another.
For example, if you have a door family with a type parameter for door width, changing the width in the type properties will update the width for all doors of that type throughout the project. Instance parameters, on the other hand, apply to individual instances of a family type and allow for unique properties to be set for each instance. Changes to instance parameters affect only the specific instance of the element. These parameters are useful for properties that need to be unique for each instance, such as specific location, orientation, or a particular mark or identifier. For instance, if you have a door family with an instance parameter for door number, you can assign a unique door number to each door instance without affecting other doors of the same type.
All the above properties collectively encompasses all the parameters associated with the Element of the Data Exchange.
The InstanceParameters and TypeParameters collections contain both Parameters and ParameterSets. Use recursive logic to extract details. A ParameterSet contains a list of Parameters and these Parameters can hold both Parameter and ParameterSet
In the following code sample parameter.ParameterDataType returns ParameterSet and ParameterSet.Parameters returns a list of parameters.
The Parameters obtained from the ParameterSet are same as simple parameter which contains a schemaid and its value and type.
private void ExtractParameterData(Parameter parameter)
{
if (parameter.ParameterDataType == ParameterDataType.ParameterSet)
{
// Extract parameter set data like ParameterSet id, name, description, and parameters
Console.WriteLine((parameter as ParameterSet).Id);
Console.WriteLine((parameter as ParameterSet).Name);
Console.WriteLine((parameter as ParameterSet).Description);
Console.WriteLine((parameter as ParameterSet).Parameters.Count);
foreach (var param in (parameter as ParameterSet).Parameters)
{
ExtractParameterData(param);
}
}
else
{
// Extract parameter data like Parameter name, type, value, etc.
Console.WriteLine(parameter.Name);
Console.WriteLine(parameter.ParameterDataType);
Console.WriteLine(parameter.Value);
}
}
foreach (var parameter in Element.InstanceParameters)
{
ExtractParameterData(parameter);
}
foreach (var parameter in Element.TypeParameters) // For Revit type parameters only.
{
// Implement any required operations for type parameters here
}
// Get type parameters - two options:
// Option 1: Get all type parameters
// var typeParametersDict = data.GetTypeParameters();
// Option 2: Get specific type parameters
var typeParametersDict = data.GetTypeParameters("element type1", "element type2");
foreach (var item in typeParametersDict)
{
foreach (var parameter in item.Value)
{
ShowParameter(parameter);
}
}
In the above code, data represents instance of ElementDataModel which can be created using the ElementDataModel.Create method.
Retrieve Parameters from Geometry
Access parameters attached directly to geometry objects. These parameters persist through the exchange lifecycle and are exported to formats like NWC for Navisworks, where each geometry piece displays its specific metadata.
Access Geometry Parameters
// Get geometries for elements
var geometries = await ElementDataModel.GetElementGeometriesByElementsAsync(
ElementDataModel.Elements
);
foreach (var kvp in geometries)
{
var element = kvp.Key;
var elementGeometries = kvp.Value;
Console.WriteLine($"Element: {element.Name}");
foreach (var geometry in elementGeometries)
{
Console.WriteLine($" Geometry parameters:");
foreach (var param in geometry.Parameters)
{
Console.WriteLine($" {param.Name}: {param.Value}");
}
}
}
Find Specific Geometry Parameters
// Find geometry with specific material
foreach (var element in ElementDataModel.Elements)
{
var geometries = await ElementDataModel.GetElementGeometriesByElementsAsync(
new[] { element }
);
foreach (var geom in geometries[element])
{
var materialParam = geom.Parameters
.FirstOrDefault(p => p.Name == "Material");
if (materialParam?.Value?.ToString() == "Steel")
{
Console.WriteLine($"Found steel geometry in element: {element.Name}");
}
}
}
Extract Geometry Parameter Data
private void ExtractGeometryParameters(IElementGeometry geometry)
{
foreach (var parameter in geometry.Parameters)
{
Console.WriteLine($"Parameter: {parameter.Name}");
Console.WriteLine($" SchemaId: {parameter.SchemaId}");
Console.WriteLine($" Value: {parameter.Value}");
Console.WriteLine($" Type: {parameter.ParameterDataType}");
if (parameter is ParameterSet paramSet)
{
Console.WriteLine($" Contains {paramSet.Parameters.Count()} sub-parameters");
foreach (var subParam in paramSet.Parameters)
{
ExtractGeometryParameters(subParam);
}
}
}
}
// Use the extraction method
var geometries = await ElementDataModel.GetElementGeometriesByElementsAsync(
ElementDataModel.Elements
);
foreach (var kvp in geometries)
{
foreach (var geometry in kvp.Value)
{
ExtractGeometryParameters(geometry);
}
}
For comprehensive information on creating, updating, and deleting geometry parameters, see Working with Geometry Parameters.
Related operations:
- Add Parameters to Geometry - Create geometry parameters
- Update Geometry Parameters - Modify parameter values
- Delete Geometry Parameters - Remove parameters
Retrieve Transformation of elements
The Element object contains a Transformation attribute using which you can retrieve the transformation of elements.
var Transformation = Element.Transformation
Query design instances
The ElementDataModel class provides methods to find all elements that instantiate a specific design.
GetDesignInstancesBySourceId
Returns all elements that have instantiated a design by its source id.
// Find all elements using a specific design
var instances = elementDataModel.GetDesignInstancesBySourceId("design_123");
foreach (var element in instances)
{
Console.WriteLine($"Element {element.Id} uses this design");
}
GetDesignInstancesByName
Returns all elements that have instantiated a design by its name.
// Find all instances of a door design by name
var doorElements = elementDataModel.GetDesignInstancesByName("StandardDoor");
Console.WriteLine($"Found {doorElements.Count()} door instances");
Note: Design source ids are unique, while design names may not be. Use GetDesignInstancesBySourceId when you need to query a specific design.
Retrieve element Geometry
The process of retrieving element geometry can be categorized into two types: Primitive and BRep/Mesh. The ElementDataModel class provides a method to facilitate this retrieval.
The SDK supports various geometry types, including complex geometries with large datasets:
- Contour curves: Topographic maps where each contour line contains thousands of curve segments
- Alignment curves: Road or railway alignments with complex geometry
- Terrain surfaces: Large surface meshes with many vertices and faces
- Standard primitives: Points, lines, arcs, and other basic geometric elements
All geometry types are retrieved using the same methods regardless of size or complexity.
Method: GetElementGeometriesByElementsAsync
In ElementDataModel class, you will find the method GetElementGeometriesByElementsAsync. This method returns a dictionary of Elements and their associated geometries.
Dictionary<Element, IEnumerable<ElementGeometry>> ElementGeometriesMap = ElementDataModel.GetElementGeometriesByElementsAsync(ElementDataModel.Elements)
Optional Argument: GeometryOutputOptions
The GetElementGeometriesByElementsAsync method also accepts an optional argument, a GeometryOutputOptions object, which allows you to retrieve the element geometry based on your specific requirements.
The following code sample demonstrates how to pass GeometryOutputOptions to the GetElementGeometriesByElementsAsync method to retrieve the geometry in mesh object format:
var options = new GeometryOutputOptions { MeshOutputFormat = MeshOutputFormat.Mesh }
var geometries = await elementDataModel.GetElementGeometriesByElementsAsync(elementDataModel.Elements, options);
If no options are provided, the default behavior will return FileGeometry for both .obj and .stp files.
- MeshOutputFormat.Mesh: Returns all geometries with Mesh/obj data as MeshGeometry.
- MeshOutputFormat.OBJ: Returns all geometries with Mesh/obj data as FileGeometry with .obj file paths.
- BrepOutputFormat.STEP: Returns all geometries with STEP data as FileGeometry with .stp file paths.
- ReportDownloadProgress: When
false, the call does not update the SDK’s built-in download progress step. Default istrue. Use this when your host reports progress for the containing operation. See Opt out of download progress for a geometry call.
Note:
- The MeshOutputFormat option will only affect mesh data, such as geometries with .obj files or Mesh objects. Geometries that are STEP files will still be returned as FileGeometry with a file path to a .stp file..The MeshOutputFormat option only affects mesh data. STEP files still return FileGeometry.
By using the GetElementGeometriesByElementsAsync method and the GeometryOutputOptions option, you can customize the retrieval of element geometry to suit your specific needs.
Resolving the element’s effective render style
An element can carry a render style at two levels: on the geometry and, as of SDK v8.0.0, directly on the element instance via IElement.RenderStyle. Some authoring applications (for example, Inventor) attach a body or instance color to the element instance — that override was previously not readable through the SDK.
When rendering elements, read the instance-level override first and fall back to the geometry-level style:
foreach (var element in elementDataModel.Elements)
{
var geometries = await elementDataModel.GetElementGeometriesByElementsAsync(new[] { element });
var geometry = geometries.FirstOrDefault();
var style = element.RenderStyle ?? geometry?.RenderStyle;
if (style != null)
{
ApplyColor(target, style.RGBA, style.Transparency);
}
}
Note: IElement.RenderStyle returns null when no instance-level override is set. Most elements have no override — always null-check.
For the full pattern, troubleshooting, and rationale, see Resolve an element’s render style.