Summary
This article provides a guide on how to prepare a CSV file for Bulk Search and outlines the detailed steps required to upload it successfully. It explains the necessary preparations for your file, including formatting and structuring the data correctly to meet the system’s requirements. It also walks you through the entire upload process step-by-step, ensuring that you understand how to submit your file without encountering any errors.
Before you begin
- Use the Bulk Search template available through Download template, which appears when you select New Bulk Search. A template is also included at the bottom of this article.
- Save the completed file as a UTF-8 CSV.
- Ensure every row contains at least one searchable identifier: NPI, TIN, organization name, or a complete first-and-last-name pair.
- Confirm that the data is appropriate for your organization and that personally identifiable information is handled according to your organization’s procedures.
Build the CSV file
The file must contain all six headers exactly as shown below. Headers are case-sensitive. Columns may be empty, and extra columns are ignored.
| Column | Required | Rules |
|---|---|---|
externalId |
No | Your organization’s row identifier. It is returned in results and exports and is the most reliable way to reconnect results to the source spreadsheet. |
npi |
No | Ten digits beginning with 1 or 2. Dashes and spaces are removed automatically. |
tin |
No | Exactly nine digits after non-digit characters are removed. The value is treated as an SSN for the SSDMF check. |
firstName |
No | Two to 40 characters. Must be provided together with lastName. Accents are folded automatically. |
lastName |
No | Two to 40 characters. Must be provided together with firstName. Accents are folded automatically. |
organizationName |
No | Two to 200 characters. |
Searchable row examples
- An NPI by itself
- A TIN by itself
- An organization name by itself
- A complete first-and-last-name pair
- An NPI combined with a name or organization name
A row with only an incomplete name pair, invalid identifiers, or no searchable fields is not searched. It appears in the error report instead.
Duplicate rows
Exact duplicate rows are silently removed before processing. The first occurrence is retained. If the processed row count is lower than the number of rows in the original file, compare the original and post-deduplication counts in the job summary.
Upload and start the search
- Open Instant Search from the left navigation.
- Select the Bulk Search tab.
-
Select New Bulk Search.
-
Review the sources shown in the upload dialog. *Please note: Available sources depend on your contracted services. To add sources, contact support@providertrust.com
- Attach the completed CSV file either by dragging and dropping the file or by standard file browser selection.
- Review the file checks and row preview.
- Select Start Search.
The upload dialog checks that the file is a CSV, is not empty, is within the size limit, and contains the required headers. A missing header blocks the upload and identifies the missing column by name.
The initial upload check does not validate every row. A successful file preview or green upload message does not guarantee that all rows will pass server-side validation.
After selecting Start Search, the file is uploaded to your organization’s secure storage and the search runs in the background. You can leave the page while processing continues.
How processing works
- Validate: Each row is cleaned and checked against the CSV rules. Invalid rows are written to an error report.
- Batch: Valid rows are divided into batches of up to 500 rows.
- Search: Each valid row runs every applicable check included in your organization's plan. A failing row is retried up to three times.
- Record: Every searched row receives its own search-history record.
Invalid rows do not prevent valid rows from running. For example, a file with 990 valid rows and 10 invalid rows produces results for the 990 valid rows and an error report for the 10 invalid rows. A file with no valid rows fails without running a search.
Uploads are processed one at a time in oldest-first order. Large files can delay processing.
Track job progress
The Bulk Search history table shows one row per uploaded file, including the Search Date, File Name, the Searched By user's email address, Status, and an Error Report download when one exists. The table reloads when the page opens or after a new upload.
You can track your upload’s progress with the following three statuses.
| Status | Meaning | What to do |
|---|---|---|
| PROCESSING | The upload was received, or searches are still running. | Open the job to view the processing panel. The detail page refreshes every 15 seconds. |
| COMPLETE | All searchable batches have finished, and results are available. | Open the job to review results. Check the Error Report column because a completed job may still contain skipped invalid rows. |
| FAILED | The file did not produce results. | Open the job details and review the failure message and error report. Correct the file and upload it again. |
Important operating rules
- Invalid rows do not block valid rows. A file with both valid and invalid rows can complete successfully.
- A file with zero valid rows fails without running searches or charging your organization.
- Exact duplicate rows are silently dropped; the first occurrence is retained.
- Uploads run oldest first, one at a time across the platform. Large files may take hours.
- Each searched row becomes an individual search-history record, but Bulk Search results are viewed from the Bulk Search page rather than the standard Search History tab.
- Duplicate exclusion findings from multiple identifiers are collapsed into one result for the subject.
Comments
0 comments
Please sign in to leave a comment.