How To: Create an Organization File using Hierarchy – ProviderTrust Support Center

Summary

This article explains how to create and upload an Organization File in the ProviderTrust application, including required and optional data fields, formatting rules, and error prevention tips. Our accepted file formats are .csv (UTF-8) and .psv. A file template is provided at the bottom of this article, and support is available for additional assistance.

Overview

The Organization File using Hierarchy is used to add or update organization-level data within your ProviderTrust system and assign subjects to an organizational hierarchical tree. This article provides detailed guidance on how to prepare and format the file correctly to ensure successful upload and processing.

Who Should Use This File

This format is intended for clients using the Hierarchy (up to 5-levels) configuration. If your organization uses the legacy business unit and network model, use the applicable legacy individual file format instead; that format does not include the Node External ID column.

If you are unsure which model you’re using, please reach out to support@providertrust.com.

Prerequisite: Create the Hierarchy First

Before uploading an Individual File using Hierarchy, the hierarchy nodes referenced in the file must already exist in your ProviderTrust system. Create and maintain the nodes through a hierarchy file or the Identity API, then use the node's exact Node External ID in the individual file. A Node External ID that does not match an existing hierarchy node cannot assign the subject to the intended location.

For information on how to build a Hierarchy file, visit our article How To: Create a Hierarchy File.

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 - Organization File - 04 29 2020.csv`)
Template Requirements	A downloadable file template is available at the bottom of this article. Remove the example data in Row 2 before uploading.
SFTP folder path	(`/services/monitor/organization/`)
Multiple Records	Multiple rows may share the same External ID, indicating multiple addresses or attributes for a single organization. This approach allows for the inclusion of multiple addresses or other related information for a single entity.
Removal of Organizations	To remove an organization, enter a termination date in the End Date column or contact your Implementation Manager to enable the auto-termination feature. For more information regarding our best practices, refer to ProviderTrust Best Practices for Ending Monitoring.

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
External ID	Required The External ID is a variable-length field and can include letters, numbers, and special characters. It must be unique across your entire organization. This is the key identifier to add, update, or remove a subject. There is a 255-character limit. If a subject appears multiple times with the same external ID but different DOB, NPI, TIN, or SSN, all rows with that ID will error and display within the error report. If a subject appears multiple times with the same external ID but any name variation (first, middle, or last), all rows with that ID will error and display within the error report. UI Visibility: Yes Included in Reports: Yes
Type	Required Specifies record type; must be Exact Value = "Organization" UI Visibility: Yes Included in Reports: Yes
Business Name	Required Legal Name of Business (Example: ABC Company, Inc.). Business name 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: Yes
Does Business As	Optional “Doing Business As” name is associated with the individual or entity. This is the trade name or alias under which the provider or organization operates, which may differ from the legal name. "Does Business As" is a variable-length field and can include letters, numbers, and special characters. There is a 255-character limit. UI Visibility: Yes Included in Reports: Yes
TIN	Optional Tax Identification Number (TIN) associated with an individual or business. TIN must be exactly 9 digits, including leading zeros, and must not contain any dashes. UI Visibility: Yes Included in Reports: Yes
NPI	Optional NPI must be exactly 10 digits. Leaving this field blank will not fail the file. UI Visibility: Yes Included in Reports: Yes
Taxonomy	Optional - Determined during the Implementation process Can be 1 to many. Taxonomy is a variable-character field and can include letters, numbers, and special characters. Taxonomy can be used to supply customized data. There is a 255-character limit. Leaving this field blank will not fail the file. UI Visibility: Yes Included in Reports: No
License Type	Optional (if license monitoring services are contracted) License type is a variable-character field and can include letters, numbers, and special characters. There is a 255-character limit. The data within this column can be left blank if not contracted for license monitoring. UI Visibility: Yes Included in Reports: Yes
License Issuer	Optional (if license monitoring services are contracted) License Issuer is a variable-length character field and can include letters, numbers, and special characters. There is a 255-character limit. The data within this column can be left blank if not contracted for license monitoring. UI Visibility: Yes Included in Reports: Yes
License Number	Optional (if license monitoring services are contracted) License Number is a variable-length field and can include letters, numbers, and special characters. There is a 255-character limit. The data within this column can be left blank if not contracted for license monitoring. UI Visibility: Yes Included in Reports: Yes
License Issued	Optional (if license monitoring services are contracted) Must be in the following format: yyyy-mm-dd.The data within this column can be left blank if not contracted for license monitoring. UI Visibility: Yes Included in Reports: Yes
License Expiration	Optional (if license monitoring services are contracted) Must be in the following format: yyyy-mm-dd. The data within this column can be left blank if not contracted for license monitoring. UI Visibility: Yes Included in Reports: Yes
Document Type	Optional - Determined during Implementation Document Type should only be used under specific circumstances and should be discussed during Implementation. Two types are available today: Certificate of Insurance and Credential Form. Document Type 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: Yes
Document Expiration Date	Optional - Determined during Implementation Document Type should only be used under specific circumstances and should be discussed during Implementation. Must be in the following format: yyyy-mm-dd There is a 255-character limit. UI Visibility: Yes Included in Reports: Yes
Address Type	Optional: String Value Address Type defines the purpose or category of an address. Common examples include Home Work Billing Shipping Mailing Address Type is a variable character field and can include letters, numbers, and special characters. Address Type can be used to supply customized data. Multiple addresses are supported for organizations and entities. Each address entered will display in the system as a separate record tied to the same subject. There is a 255-character limit. UI Visibility: No (option to concatenate Type name with Address Name) Included in Reports: No
Address Name	Optional The Address Name serves as an additional identifier or label for the address, such as "Corporate Office" or "HR Department." It is not utilized in our screening processes and may be left blank. The Address Name is a variable-length character field that may contain letters, numbers, and special characters. Address Name can be used to supply customized data. Multiple addresses are supported for organizations and entities. Each address entered will display in the system as a separate record tied to the same subject. 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). ProviderTrust prefers that home addresses be provided for individuals. A business address may be included only if it is the sole available address. 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 State is a variable-length field and can include letters, numbers, and special characters. There is a 255-character limit. UI Visibility: Yes Included in Reports: No
Zip	Optional Must be either 5 or 9 numeric digits (no alpha), accepted formats include 12345 12345-6789 123456789 An invalid ZIP will error out the row. Leaving this field blank will not fail the file. UI Visibility: Yes Included in Reports: No
County	Optional County 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
Country	Optional Country is a variable-length field and can include letters, numbers, and special characters. There is a 255-character limit. UI Visibility: Yes Included in Reports: No
End Date	Required - Determined during Implementation End date sets a date for monitoring to end for an organization as well as removes the organization from the Active Population list. A date must be supplied to end monitoring for a subject; it must be in yyyy-mm-dd format. This date represents an "up to" date. A runnable is executed periodically throughout the day to terminate subjects on that date. If a client enters today's date, the termination will occur the first time the runnable runs on that date. End Date should be left blank for all active subjects. If a date is unable to be supplied, an auto-term functionality will be discussed during implementation. For more information regarding our best practices, refer to ProviderTrust Best Practices for Ending Monitoring. Note: If the same External ID appears on multiple rows, the End Date must be consistent across those rows or the file may error. Refer to How To: Review File Errors (EndDate/Data Mismatch). UI Visibility: Yes Included in Reports: Yes
Node External ID	Required - Determined during Implementation The Node External ID is the client-assigned unique identifier for a hierarchy node. When included in the individual/subject file, it specifies which node in the client's 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 within a client (max 255 characters) Matching is case-insensitive It is the same External ID (Ext ID) that is defined when creating nodes via the hierarchy file or Identity API Node Zero always has the External ID `CLIENT_DEFAULT` If a subject's Node External ID is blank or doesn't match a valid node, the subject lands on Node Zero (the root node) UI Visibility: Yes Included in Reports: Yes