Import a hierarchy

Learn more about how to use the Import Hierarchy API to import hierarchy data from a CSV or JSON file.

Use the Import Hierarchy to import hierarchy data in bulk. This operation requires the MDM.Data.Hierarchy permission with the CREATE privilege.

HTTP method and endpoint

Use the following HTTP method and endpoint path to submit the request:

POST https://<environment>.reltio.com/reltio/api/{tenantId}/hierarchies/import

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`Bearer <token>`	Yes
`Content-type`	`multipart/form-data`	Yes

Request body

The request body is a JSON array of connection definition objects.


Field	Type	Required	Description	Accepted values / Default
`format`	String	No	The import file format.	`CSV` or `JSON`. Default: `CSV`
`disconnectPolicy`	String	No	Determines what happens if not all objects are connected in a hierarchy with the same type, name, and version.	`PREVENT` or `CREATE_MULTIPLE`. Default: `PREVENT`
`conflictsPolicy`	String	No	Determines how to handle conflicts in connection dates for defined hierarchies.	`FORBID` or `MERGE`. Default: `FORBID`
`errorPolicy`	String	No	Determines what happens when individual lines in the imported file are in an incorrect format.	`IGNORE` or `FAIL`. Default: `FAIL`
`file`	File	Yes	The file that contains the hierarchy definition.	CSV or JSON file
`version`	String	No	The version name of the hierarchy.	Any string. Default is none.
`startDate`	Date	No	The start date of the connection.	Date format YYYY-MM-DD.
`endDate`	Date	No	The end date of the connection.	Date format YYYY-MM-DD.

Example CSV and JSON file

The following example shows the content of an import CSV file.


# hiearchies with no versions
configuration/hierarchyTypes/HierarchyType,Hierachy Name,0JecJqU,2YCLdAuY
configuration/hierarchyTypes/HierarchyType,Hierachy Name,2YCLdAuY,2YCLdFAo

# hiearchies with versions
configuration/hierarchyTypes/HierarchyType,Hierachy Name,Version Name,0JecJqU,2YCLdAuY
configuration/hierarchyTypes/HierarchyType,Hierachy Name,Version Name,2YCLdAuY,2YCLdFAo

# hiearchies with no versions, but with start-end dates of connections
configuration/hierarchyTypes/HierarchyType,Hierachy Name,0JecJqU,2YCLdAuY,2026-01-01,2026-02-28
configuration/hierarchyTypes/HierarchyType,Hierachy Name,2YCLdAuY,2YCLdFAo,2026-01-05,2026-03-30

# hiearchies with versions, and start-end dates of connections
configuration/hierarchyTypes/HierarchyType,Hierachy Name,Version Name,0JecJqU,2YCLdAuY,2026-01-01,2026-02-28
configuration/hierarchyTypes/HierarchyType,Hierachy Name,Version Name,2YCLdAuY,2YCLdFAo,2026-01-05,2026-03-30

The following example shows the content of an import JSON file.

[
  {
    "name": "test-hierarchy",
    "type": "test-type",
    "version": "1.0",
    "connections": [
      {
        "parentId": "parent1",
        "childId": "child1",
        "startDate": "2025-01-01",
        "endDate": "2025-12-31"
      }
    ]
  }
]

Example request

The following example shows a CSV upload request. To upload a JSON file, set format to JSON and upload a JSON file in the file field.

POST /import
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=---boundary


format=CSV
disconnectPolicy=PREVENT
conflictsPolicy=FORBID
errorPolicy=FAIL
file=hierarchies.csv

Response fields

The following table describes the fields returned in the response body, which is an array of hierarchy connection objects.


Field	Type	Description
`createdInstances`	Object	A map of hierarchy names to arrays of created instance IDs. Instance ID = `HierarchyId.VersionId`
`failedHierarchies`	Array of strings	The names of hierarchies that could not be loaded.

Example response

The following example shows the response body.

{
  "createdInstances": {
    "Hierarchy One": [
      "0ABlc0A.0ABlgGQ"
    ],
    "Hierarchy Two": [
      "0ABlc0A.0ABlB1z"
    ]
  },
  "failedHierarchies": [
    "Failed Hierarchy Name"
  ]
}

Unify and manage your data