Request

Response

    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:

    PropertyTypeDescription
    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 accessible
    • 403: Insufficient permissions to access the exchange
    • 404: Exchange has been deleted
    • Other codes: Network errors, service unavailable, or other transient issues

    Important: Always check ValidationStatus.IsSuccess before 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");
    
    Show More

    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}");
        }
    }
    
    Show More

    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
    }
    
    Show More

    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
        };
    
    Show More

    ​ 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.

    Load exchange progress dialog

    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();
    
    Show More

    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.

    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;
        }
    
    Show More

    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}");
    }
    
    Show More

    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);
                }
            }
    
    Show More

    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}");
            }
        }
    }
    
    Show More

    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}");
            }
        }
    }
    
    Show More

    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);
        }
    }
    
    Show More

    For comprehensive information on creating, updating, and deleting geometry parameters, see Working with Geometry Parameters.

    Related operations:

    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.

    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 v7.6.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);
        }
    }
    
    Show More

    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.