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. It must be unique within 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"
      }
    ]
  }
]

Note: Hierarchy names in an import file must be unique within the tenant. Version names must be unique within each hierarchy.

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"
  ]
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`400 Bad Request`	The request contains invalid or missing parameters.	Review the error message, correct the request as indicated, and submit the request again. For example, if the error identifies a duplicate version name, specify a unique name before resubmitting the request.

Unify and manage your data