How To: Create a Hierarchy File – ProviderTrust Support Center

Summary

This article summarizes the ProviderTrust Hierarchy File process, including the file format and template requirements, naming conventions, SFTP upload instructions, and validation guidance. It also explains the hierarchy fields—required identifiers such as External ID and Name, along with optional address and location information—and the formatting rules that help ensure successful processing.

Overview

The Hierarchy File creates and maintains your organization’s hierarchy in ProviderTrust. Use it to add new hierarchy nodes and update existing nodes. The file can be uploaded in .csv (UTF-8) or .psv format and includes required fields such as External ID and Name, along with optional address and location details. Follow the template and formatting requirements carefully to help ensure a successful upload and processing.

What Is a Hierarchy?

A hierarchy is a tree-shaped structure that shows how your organization is organized. Each node is one location or organizational unit, such as a corporate office, region, state, facility, department, or practice. A node can have a parent above it and child nodes below it. For example: Corporate Office → East Region → Tennessee → Nashville Facility.

The hierarchy file creates or updates these nodes. It is separate from the individual and organization files that assign subjects (such as employees, providers, organizations, and vendors) to hierarchy locations.

How Parent ID and External ID Build the Tree

External ID is the unique identifier for the current node. Parent ID tells ProviderTrust where that node belongs and must match the parent node’s External ID when the node is being placed under another node from the file or an existing hierarchy. Nodes with a blank Parent ID are added under the client’s default root, which ProviderTrust creates for the client organization.

Example: In the sample file below, the Nashville Facility row rolls up to the East Region row, so the Nashville Facility has EAST-01 in its Parent ID. If the East Region and West Region rows are added without a Parent ID, they become top-level nodes under the client’s default root.

Example: A Small Hierarchy File

The following example shows a corporate node, two regional nodes, and two facilities.

Note: The corporate example row (row 2) is optional when the client’s default root already represents the client organization.

Parent ID	External ID	Name	Address Line 1	Address Line 2	City	Zip	State
	CORP-01	Corporate Office	100 Main Street		Nashville	37201	TN
CORP-01	EAST-01	East Region
EAST-01	NSH-01	Nashville Facility	200 Oak Avenue	Suite 300	Nashville	37203	TN
CORP-01	WEST-01	West Region
WEST-01	DEN-01	Denver Facility	500 Market Street		Denver	80202	CO

In this example, CORP-01 represents a corporate-level node in the submitted file. EAST-01 and WEST-01 are children of CORP-01, and NSH-01 and DEN-01 are children of their respective regions. If the corporate row is not included, rows such as EAST-01 and WEST-01 can be submitted with a blank Parent ID; ProviderTrust adds them as top-level nodes under the client’s default root.

File Format Requirements

Specification	Details
Accepted File Types	`.csv` (UTF-8 encoded) or `.psv`
Header Row (Row 1)	Must remain unchanged. Do not edit or rename any column headers. Modifying this row may result in file errors.
File Naming Convention	Use your company name and date (e.g., `Test Client - Hierarchy File - 04 29 2020.csv`)
Template Requirements	A downloadable file template is available at the bottom of this article. Remove all example data in before uploading, including guidelines in Row 2.
SFTP folder path	(`/services/hierarchy/`)

Uploading Your File

Once your file is complete and validated, upload it securely to ProviderTrust via SFTP.

For detailed upload instructions, refer to How To: Upload Data to SFTP

File Specifications

Column Header	Description
Parent ID	Optional Parent ID identifies the hierarchy node that should serve as the parent of the current record. It establishes the record’s position and relationship within the organizational hierarchy. The Parent ID should match the parent node’s External ID. If left blank, the record is added as a top-level node under the client’s default root, which is created for the client organization. UI Visibility: Yes Included in Reports: No
External ID	Required The External ID is the unique identifier for a hierarchy node. It specifies which node in the hierarchy tree the subject should be assigned to. It links the subject to a specific location in the organization's hierarchy. Key characteristics: Must be unique (max 255 characters) Matching is case-insensitive UI Visibility: Yes Included in Reports: Yes
Name	Required The Name field serves as an identifier or label for the hierarchy node, such as "Corporate Office" or "East Coast Division." Name is a variable-length character field that may contain letters, numbers, and special characters. Name can be used to supply customized data. There is a 255-character limit. UI Visibility: Yes Included in Reports: No
Address Line 1	Optional Address Line 1 should include the street address (e.g., 123 Main Street). Address Line 1 is a variable-character field and can include letters, numbers, and special characters. There is a 255-character limit. UI Visibility: Yes Included in Reports: No
Address Line 2	Optional Address Line 2 should specify secondary address details, including apartment, suite, or unit numbers (e.g., Apt 4B, Suite 300). Address Name 2 is a variable-character field and can include letters, numbers, and special characters. There is a 255-character limit. UI Visibility: Yes Included in Reports: No
City	Optional City is a variable-length character field and can include letters, numbers, and special characters. There is a 255-character limit. UI Visibility: Yes Included in Reports: No
State	Optional If given, it is validated against the Proper name of the state or abbreviation, i.e., Tennessee (not case-sensitive), or TN. There is a 255-character limit. UI Visibility: Yes Included in Reports: No
Zip Code	Optional Must be either 5 or 9 numeric digits (no alpha); accepted formats include: 12345 12345-6789 123456789 An invalid ZIP will cause the row to error out. Leaving this field blank will not fail the file. UI Visibility: Yes Included in Reports: No

Creating New Nodes and Updating Existing Nodes

Use a stable, unique External ID for each node. When an existing node is included again with the same External ID, its row can be used to maintain or update that node’s information. Do not change an existing node’s External ID unless you intend to create or reconcile a different node; if you are unsure how an update will be handled, contact Client Care before uploading.

Recommended Row Order

Arrange the file with parent rows before their child rows. Although the Parent ID and External ID values define the relationship, parent-first ordering makes the file easier to review and helps you identify missing parent records before upload. Include a parent row in the file when you are creating it in the same upload as its children.

Validation Checklist Before Upload

Use the provided template and leave the header row unchanged.
Confirm that every row has the required External ID and Name.
Confirm that every External ID is unique, spelled consistently, and no longer than 255 characters.
Check that every nonblank Parent ID exactly matches an External ID in the hierarchy.
Confirm that nodes intended to be top-level entries have a blank Parent ID; ProviderTrust adds them under the client’s default root.
Check for circular relationships, such as a node being its own parent or two nodes pointing to each other.
Make sure the hierarchy has no unintended orphan nodes or disconnected branches.
Place parent rows before child rows and remove the example data from Row 2.
Validate ZIP values: use 5 or 9 numeric digits, with an optional hyphen in the 9-digit format.
Save the file as UTF-8 .csv or .psv, use the required naming convention, and confirm the correct delimiter for the chosen format.

Common Mistakes to Avoid

Putting a node’s name, rather than its External ID, in Parent ID.
Reusing an External ID for two different nodes.
Leaving required fields blank or changing the template’s column headers.
Uploading the template’s sample row or shifting values into the wrong columns.
Using an invalid ZIP format or adding unexpected spaces and characters to identifiers.
Creating a circular reference or referencing a parent that is not present or has not been established.