CAREWare CSV Specifications

Kevin Ricciardo

Aug 20, 2026

3629

Purpose	Explain how CAREWare Provider Data Import (PDI) interprets standardized CSV files, identifies clients, maps values, and determines whether incoming records are added, updated, or deleted.
Who should do this	CAREWare administrators, data managers, interface staff, and others who prepare or validate CAREWare CSV imports.
Use this guide when	A source file already follows the CAREWare CSV template or when another import workflow needs the CAREWare CSV field definitions as its target.
Main warning	Import Settings control matching and update behavior. The provider and source name in exp_provider.csv must match the intended Import Settings before production data is processed.
Detailed explanation of CAREWare CSV format	CAREWare CSV File Specifications
Downloadable CAREWare CSV Template	CAREWare CSV Template

Quick path

Administrative Options > Data Import and Export Features > Provider Data Import

Before you begin

CAREWare CSV imports are most reliable when the incoming file structure, client matching method, and provider Import Settings are treated as one configuration. Confirm the expected Source Name, client match field, and update rules before using a production file.

Important
Use a small test file first and review Import History, missing mappings, and client matching issues before processing a large production import.

How CAREWare CSV imports work

The Provider Data Import accepts standardized CSV files that represent CAREWare entities such as clients, services, diagnoses, tests, referrals, and assessments. Values that already match native CAREWare values are mapped automatically; other source values can be mapped through PDI value mapping. Current workflows use CSV or other supported interfaces rather than the deprecated MDB import/export format.

An import is evaluated record by record. CAREWare compares the incoming record with the matching fields defined for that record type. A matching record can be updated, a nonmatching record can be added, and a matching record can be deleted when the incoming is_delete value is set to yes. Import Settings can further control whether clients are matched, added, updated, skipped, or routed for manual matching.

Package and file requirements

Requirement	CAREWare CSV expectation
CSV format	Use standard RFC 4180 CSV formatting.
File names	Use the exact PDI table names from the CAREWare CSV template, such as exp_service.csv.
Header row	The first row contains CAREWare column names that match the specification or template.
ZIP contents	Include at least one client-level data file and exp_provider.csv. Attachments, when present, belong in an attachments folder.
Optional columns	Optional columns may be omitted, but keeping template columns and leaving unavailable values blank reduces avoidable format errors.

Tip

For a service-only import, exp_service.csv and exp_provider.csv can be sufficient because the service file carries the client-matching fields needed for that record.

Client identification and matching

Client-level CSV tables carry first_name, last_name, sex_at_birth, dob, urn_suffix, and match_id fields so each imported record can be associated with the correct client. First name, last name, sex at birth, and date of birth form the CAREWare URN matching fields. The urn_suffix distinguishes clients who would otherwise share a URN; a blank suffix is treated as U.

A record can be matched with complete URN fields or with match_id when Import Settings are configured to match on Client ID or a custom field. Records with incomplete URN data can still match an existing client through match_id, but a new client can only be added when the URN fields needed to identify that client are complete. When matching on URN, match_id is not used to update Client ID or custom client values; those updates belong in exp_client.

Important
When Manual Client Matching is enabled, CAREWare can score similar URNs as potential matches. If automatically add new clients is selected there is an increased chance that duplicate clients are added during the import process.

For privacy-sensitive exchanges, current CAREWare guidance notes that match_id can carry an eUCI, Client ID, custom field value, or another configured matching value. This can reduce reliance on personally identifying matching fields when the receiving Import Settings are configured accordingly.

Record matching behavior

Each CSV table has its own matching rule. The table below summarizes the fields CAREWare uses to recognize the same record. When a match is found, incoming values generally update that record unless the record type has a specific exception.

Record type	Matching basis
Client	Generated URN; potential score-based manual match for similar URNs.
ADAP enrollment history	Client, date, and provider; used for the ADAP provider.
Annual review	Client and year; used for Annual Review custom field data.
Appointment	Client, provider, service type, and date; dates within +/-1 day are treated as a match.
Attachment	Client, attachment list, date, and provider.
Case note	Client, date, and provider; a matching note is overwritten rather than appended.
Counseling and testing	Client, date, and provider.
Custom subform	Client, date, and provider.
Diagnosis	Client, date, provider, and diagnosis code.
Drug payment	Client, date, provider, and NDC; overlap behavior can use the configured drug-overlap days.
Eligibility	Client, date, provider, and eligibility funding.
Form design data	Client, date, provider, and form design code.
Immunization	Client, date, provider, and immunization code.
Insurance assessment	Client, date, and provider; Handle Insurance settings control updates.
Medication	Client, medication code, start date, and provider
Message / Out of pocket expense / Poverty level assessment	Client, date, and provider.
Pregnancy	Client, provider, and estimated conception date; dates within 30 days are treated as the same record.
Provider	Provider name and source name in Import Settings.
Referral	Client, date referred, referring provider, service category, and referred-to site.
Relations	Provider, index client, and dependent client.
Service	Client, provider, service date, and subservice; receipts are imported with service records.
Sharing request	Client, date, and provider.
Test	Client, date, provider, and test definition.
Vital sign	Client, date, and provider.

Important

For services, srv_contract_name must exactly identify a valid contract when it is supplied. The subservice must be active for that contract and the service date must fall within the contract dates. If srv_contract_name is blank, there must be exactly one valid contract for that subservice and date.
A slightly different contract name can produce a no-valid-contract error. A blank contract name can also fail when the same subservice is active under more than one valid contract on the service date.

Custom fields and coding systems

Custom field columns are appended to the CSV table that represents the field's active CAREWare location. Custom column names begin with cst_. Safe field names replace spaces with underscores and remove special characters. Any number of custom field columns can be included when the receiving provider has the corresponding custom fields configured.

Clinical tables can use coding-system pairs to support automatic value matching. A _cs column identifies the coding system and the paired _def_code column carries the value code. When no coding system is supplied, CAREWare uses standard value mapping. Tables that accept multiple values number these pairs in sequence, such as _cs_1 / _cs_1_def_code and _cs_2 / _cs_2_def_code.

Tip
Numbered coding-system pairs are evaluated in order. Do not leave an earlier _def_code pair blank and expect CAREWare to continue to a later pair.

For service rows that contain multiple numbered service definition pairs, the same srv_date applies to all services represented on that row. Sex at birth remains a URN field; when it is blank during client import, CAREWare uses the unknown value for URN matching.

Import readiness and data quality

A stable CSV exchange should preserve the CAREWare template field names and the intended matching rules across runs. Include records added, changed, or deleted since the prior export when the receiving site depends on incremental synchronization, and preserve the chronological order of export packages so changes are applied in the expected sequence.

Check	Why it matters
Provider and Source Name	Determines which Import Settings CAREWare applies.
Client matching field	Controls whether records attach to existing clients or create potential duplicates.
Exact file and column names	Allows the PDI parser to recognize each table and field.
Value mappings	Prevents unmapped source values from holding or failing records.
Small test file	Surfaces format, mapping, contract, and matching issues before production volume is processed.
Import History review	Shows validation and processing results that should be resolved before final processing.

Troubleshooting and common questions

Why is a file rejected before mapping?

Check the ZIP for an unexpected file outside the attachments folder and confirm every CSV filename exactly matches a PDI table name.

Why did CAREWare use the wrong import behavior?

Confirm prv_name and prv_source in exp_provider.csv match the intended provider and Import Settings Source Name.

Why was a client added instead of matched?

Review the URN fields, urn_suffix, match_id, and the selected client-matching option. If appropriate, enable and review Manual Client Matching.

Why is a service reporting no valid contract?

Check srv_contract_name spelling, contract dates, and whether the imported subservice is active for the contract.

Why is a source value not accepted?

Confirm the value is a native CAREWare value, a valid coding-system value, or has a PDI value mapping.

When should DTM be used instead of CAREWare CSV?

Use DTM when the source is a flat or delimited file whose columns must be mapped into CAREWare CSV fields. This is generally used to import reports from other systems or to convert custom reports from CAREWare into an import file to correct data. Use CAREWare CSV when the file already follows the CAREWare template.

Related CAREWare guides and resources

Resource	How it helps
CAREWare CSV Specifications	Current field, file, matching, custom-field, and coding-system specification.
Import Settings	Matching, update, value-handling, service, ADAP, and automation rules.
Provider Data Import	Overview of PDI tools, holding records, mappings, and processing.
New Import	Upload requirements and validation guidance for a new PDI import.
Importing Data into CAREWare	Comparison of CAREWare CSV, SQL PDI, DTM, FHIR, and HL7 import methods.
Importing Custom Data Using PDI	Custom field template requirements for client, service, eligibility, and attachment imports.

Attachments