Bulk Data Schema Reference

Overview

BenefitFlow delivers six CSV datasets via SFTP, refreshed weekly every Saturday. Together they provide a complete picture of US employer-sponsored benefits: which employers offer what coverage, through which carriers, brokered by whom, at which offices, and the people at those brokerages and employers.

Dataset	File Pattern	Description
Employer	`EMPLOYER-YYYYMMDD.csv`	One row per employer — firmographics, benefits program details, primary broker relationship, and P&C information
Policy	`POLICY-YYYYMMDD.csv`	One row per policy per employer — the most granular view of coverage, carriers, premiums, and broker assignments
Broker	`BROKER-YYYYMMDD.csv`	One row per brokerage firm — aggregated metrics across all clients, offices, and contacts
Broker Office	`BROKER_OFFICE-YYYYMMDD.csv`	One row per office location — aggregated metrics for clients and contacts serviced by that office
Broker Contact	`BROKER_CONTACT-YYYYMMDD.csv`	One row per individual at a brokerage — professional details, licensing, and office association
Employer Contact	`EMPLOYER_CONTACT-YYYYMMDD.csv`	One row per individual at an employer — professional details and employer association

BenefitFlow aggregates data from multiple public and proprietary sources. For a complete overview, see Where does BenefitFlow’s data come from?

Entity Relationships

The six datasets connect through shared identifiers. Use these keys to join across files.

Join Keys

Relationship	From	Join Key	To	Join Key
Employer → Policies	Employer	`Employer ID`	Policy	`Employer ID`
Employer → Primary Broker	Employer	`Primary Broker ID`	Broker	`Broker ID`
Employer → Primary Broker Office	Employer	`Primary Broker Closest Office ID`	Broker Office	`Broker Office ID`
Policy → Broker	Policy	`Broker ID`	Broker	`Broker ID`
Broker → Offices	Broker	`Broker ID`	Broker Office	`Broker ID`
Broker → Contacts	Broker	`Broker ID`	Broker Contact	`Broker ID`
Broker Office → Contacts	Broker Office	`Broker Office ID`	Broker Contact	`Closest Office ID`
Employer → Employer Contacts	Employer	`Employer ID`	Employer Contact	`Employer ID`

Key Relationships

Employer → Policy is one-to-many. A single employer can have multiple policies (e.g., one for Health, one for Dental, one for Life). The Policy file is the most granular view of coverage.
Employer → Broker is surfaced two ways: the Employer file carries denormalized “Primary Broker” fields (the broker with the most business), while the Policy file shows the specific broker on each individual policy. These can differ — an employer may use Broker A for health and Broker B for dental.
Broker → Office → Contact is hierarchical. A broker firm (e.g., “Lockton Companies”) has many offices, and each contact is associated with one office.
Employer → Employer Contact is one-to-many. Employer contacts are the people at the employer (HR, benefits, executives) rather than at the brokerage. They share the same contact data model as broker contacts but are linked to an employer instead of a broker.

Employer

One row per employer. Includes firmographics, benefits program details, primary broker relationship, and P&C insurance information.

Sources: Form 5500, state-level filings, employee review platforms, Proprietary · Refresh: Weekly (Saturday)

Column	Type	Description	Example
Record Type	String	Row type identifier. Always “Employer” in this file.	`Employer`
Employer Name	String	Legal name of the employer, as filed.	`Walmart Inc`
Employer Website	String	Primary company website domain.	`walmart.com`
Employer NAICS Description	String	Industry classification (North American Industry Classification System).	`Discount Department Stores`
Employer NAICS Code	String	Numeric NAICS industry code. Single-quote prefixed to preserve leading zeros.	`'452112'`
Employer EIN	String	Federal Employer Identification Number. Single-quote prefixed.	`'710415188'`
Employer Address	String	Street address of the employer’s primary filing location.	`508 Sw 8th St`
Employer City	String	City of the employer’s primary filing location.	`Bentonville`
Employer State	String	Two-letter state abbreviation.	`AR`
Employer Zip Code	String	5-digit ZIP code. Single-quote prefixed.	`'72712'`
Employer ID	String (UUID)	BenefitFlow unique identifier for this employer. Primary key. Use to join to the Policy file.	`c86b9d4d-1b87-57dc-...`
Total Employees	Integer	Total number of employees reported by the employer.	`2076632`
Benefit Eligible Employees	Integer	Number of employees eligible for benefits.	`2076632`
Benefits Rating	Decimal	BenefitFlow-calculated score (0–5) reflecting the richness of the employer’s benefits program.	`2.4`
5500 Signor Name	String	Name of the person who signed the Form 5500 filing.	`Marty Autrey`
Phone Number	String	Employer’s primary phone number.	`(800) 421-1362`
Funding	String	Benefits funding model. Values: `Fully-Insured`, `Self-Funded`.	`Self-Funded`
Entity Type	String	Employer plan type. Values: `Single-Employer`, `Multi-Employer`, `Multiple-Employer`.	`Single-Employer`
Primary Carrier	String	Insurance carrier with the largest share of this employer’s premiums.	`Kaiser Permanente`
Line of Business	String	Comma-separated list of benefit lines the employer offers (aggregated across all policies).	`Vision,Health,Prescription Drug,...`
Total Premiums	Integer	Total annual premiums across all policies, in USD.	`1077048873`
Benefits Renewal Date	String	Month and day when the employer’s benefits renew.	`Jan 1`
Primary Broker	String	Name of the broker with the largest share of this employer’s business.	`Mercer`
Primary Broker Website	String	Website of the primary broker.	`mercer.com`
Commissions	Integer	Total commissions paid to the primary broker, in USD.	`160019`
Primary Broker Office Name	String	Display name of the primary broker’s closest office.	`"Mercer - Kansas City, MO"`
Primary Broker Closest Office City	String	City of the broker office geographically closest to the employer.	`Kansas City`
Primary Broker Closest Office State	String	State of the closest broker office.	`MO`
Primary Broker Closest Office Zip	String	ZIP code of the closest broker office. Single-quote prefixed.	`'64108'`
Primary Broker Closest Office Address	String	Full address of the closest broker office.	`2405 Grand Blvd Kansas City MO 64108`
Primary Broker Reported Office City	String	City of the broker office as reported on the 5500 filing (may differ from closest office).	`Wilmington`
Primary Broker Reported Office State	String	State of the reported broker office.	`MA`
P&C Renewal Date	String	Renewal date for the employer’s Property & Casualty coverage.	`Jan 1`
P&C Broker	String	Broker handling the employer’s Property & Casualty insurance.	`Marsh Usa Llc`
P&C Carrier	String	Carrier providing Property & Casualty coverage.	`Federal Insurance Company`
Primary Broker ID	String (UUID)	BenefitFlow identifier for the primary broker. Foreign key → Broker file. Blank when no primary broker is identified.	`d3fb3613-7fd4-55f6-...`
Primary Broker Closest Office ID	String (UUID)	BenefitFlow identifier for the closest broker office. Foreign key → Broker Office file.	`b787e0ee-a977-5ba8-...`
PEO	String	Professional Employer Organization, if the employer uses one.	`DSH INC`
Accounting Firm	String	Accounting firm listed on the employer’s 5500 filing.	`Ernst & Young, LLP`
Lead Source	String	Data source attribution. Always `BenefitFlow` in SFTP exports.	`BenefitFlow`
Export Date	Date	Date this snapshot was generated. Format: `M/D/YYYY`.	`4/5/2026`
Filing Date	Date	Date of the most recent Form 5500 filing for this employer.	`2025-01-31`
BenefitFlow User	String	Internal system user that generated the export. Always `sftp-export-email`.	`sftp-export-email`
BenefitFlow Employer URL	URL	Direct link to this employer’s profile in the BenefitFlow application.	`https://benefit-flow.com/Employer/...`

Policy

One row per policy per employer. An employer with Health, Dental, and Life coverage will have at least three rows. This is the most granular view of benefits coverage.

Sources: Form 5500 · Refresh: Weekly (Saturday)

Column	Type	Description	Example
Record Type	String	Row type identifier. Always “Policy” in this file.	`Policy`
Employer Name	String	Legal name of the employer.	`Walmart Inc`
Employer NAICS Description	String	Industry classification description.	`Discount Department Stores`
Employer NAICS Code	String	Numeric NAICS code. Single-quote prefixed.	`'452112'`
Employer EIN	String	Federal Employer Identification Number. Single-quote prefixed.	`'710415188'`
Employer City	String	City of the employer.	`Bentonville`
Employer State	String	Two-letter state abbreviation.	`AR`
Employer Zip Code	String	5-digit ZIP code. Single-quote prefixed.	`'72712'`
Employer ID	String (UUID)	BenefitFlow identifier for the employer. Foreign key → Employer file.	`c86b9d4d-1b87-57dc-...`
Total Employees	Integer	Total employees at the employer (denormalized from Employer file).	`2076632`
Benefit Eligible Employees	Integer	Number of benefits-eligible employees.	`2076632`
5500 Signor Name	String	5500 filing signatory.	`Marty Autrey`
Phone Number	String	Employer phone number.	`(800) 421-1362`
Funding	String	Funding model. `Fully-Insured` or `Self-Funded`.	`Self-Funded`
Entity Type	String	Plan entity type.	`Single-Employer`
Plan Name	String	Official name of the benefits plan as filed.	`WALMART ASSOCIATES HEALTH AND WELFARE PLAN`
Policy Number	String	Policy or plan sequence number.	`1`
Carrier	String	Insurance carrier underwriting this specific policy.	`Kaiser Permanente`
Line of Business	String	Comma-separated benefit types covered by this policy.	`Health, Prescription Drug, HMO`
Line of Business, Detail	String	Additional detail on the benefit line, when available.	`AD & D`
Total Premiums	Integer	Annual premiums for this specific policy, in USD.	`276335`
Covered Lives	Integer	Number of individuals covered under this policy.	`14`
PEPM Rate	Decimal	Per-Employee-Per-Month rate for this policy, in USD.	`1644.85`
Total Commissions	Integer	Total broker commissions on this policy, in USD.	`16473`
Renewal Date	String	Policy renewal date.	`Sep 1`
Primary Broker	String	Broker on this specific policy. May differ from the employer-level primary broker.	`Cbiz`
Primary Broker Website	String	Broker website.	`cbiz.com`
Commissions	Integer	Broker commissions on this policy.	`16473`
Primary Broker Office Name	String	Broker office display name.	`"Cbiz - Columbia, MD"`
Primary Broker Closest Office City	String	City of the broker office closest to the employer.	`Columbia`
Primary Broker Closest Office State	String	State of the closest broker office.	`MD`
Primary Broker Office Zip Code	String	ZIP code of the closest broker office. Single-quote prefixed.	`'21046'`
Primary Broker Office Address	String	Full address of the closest broker office.	`9841 Broken Land Pkwy Columbia MD 21046`
Primary Broker Reported Office City	String	Broker office city as reported on the filing (may differ from closest).	`Kansas City`
Primary Broker Reported Office State	String	Broker office state as reported on the filing.	`KS`
Broker ID	String (UUID)	BenefitFlow identifier for the broker on this policy. Foreign key → Broker file.	`13234d93-3d22-51e0-...`
Lead Source	String	Data source attribution. Always `BenefitFlow`.	`BenefitFlow`
Export Date	Date	Snapshot generation date. Format: `M/D/YYYY`.	`4/5/2026`
Filing Date	Date	Date of the source 5500 filing. Format: `M/D/YYYY`.	`8/31/2025`
BenefitFlow User	String	Internal export system user. Always `sftp-export-email`.	`sftp-export-email`
BenefitFlow Employer URL	URL	Direct link to the employer’s profile in BenefitFlow.	`https://benefit-flow.com/Employer/...`

Broker

One row per brokerage firm. Aggregated metrics across all of the broker’s clients, offices, and contacts.

Sources: Form 5500, Proprietary · Refresh: Weekly (Saturday)

Column	Type	Description	Example
Record Type	String	Row type identifier. Always “Broker” in this file.	`Broker`
Broker ID	String (UUID)	BenefitFlow unique identifier for this broker. Primary key.	`13234d93-3d22-51e0-...`
Broker Name	String	Name of the brokerage firm.	`Lockton Companies`
Broker Website	String	Broker’s primary website domain.	`lockton.com`
Headquarters	String	City and state of the broker’s headquarters.	`Kansas City, MO`
Total Office Locations	Integer	Number of office locations for this broker in BenefitFlow.	`60`
Total Clients	Integer	Number of employer clients associated with this broker.	`3414`
Total Contacts	Integer	Number of individual contacts at this brokerage.	`3149`
Total Commissions	Integer	Aggregate commissions across all clients, in USD.	`485351164`
Total Carrier Premiums	Integer	Aggregate premiums placed across all clients, in USD.	`8454249674`
Lead Source	String	Data source attribution. Always `BenefitFlow`.	`BenefitFlow`
Export Date	Date	Snapshot generation date. Format: `M/D/YYYY`.	`4/5/2026`
BenefitFlow User	String	Internal export system user. Always `sftp-export-email`.	`sftp-export-email`
BenefitFlow Broker URL	URL	Direct link to the broker’s profile in BenefitFlow.	`https://benefit-flow.com/Broker?brokerId=...`

Broker Office

One row per broker office location. Each office belongs to one broker firm and includes aggregated metrics for the clients and contacts associated with that office.

Sources: Form 5500, Proprietary · Refresh: Weekly (Saturday)

Column	Type	Description	Example
Record Type	String	Row type identifier. Always “Broker Office” in this file.	`Broker Office`
Broker ID	String (UUID)	BenefitFlow identifier of the parent broker firm. Foreign key → Broker file.	`13234d93-3d22-51e0-...`
Broker Name	String	Name of the parent broker firm.	`Lockton Companies`
Broker Website	String	Parent broker’s website.	`lockton.com`
Broker Office Name	String	Display name of this office.	`"Lockton Companies - Dallas, TX"`
Broker Office Address	String	Full street address of this office.	`717 N Harwood St Dallas TX 75201`
Broker Office City	String	City where this office is located.	`Dallas`
Broker Office State	String	Two-letter state abbreviation.	`TX`
Broker Office Zip Code	String	5-digit ZIP code. Single-quote prefixed.	`'75201'`
Total Clients	Integer	Number of employer clients serviced from this office.	`242`
Total Contacts	Integer	Number of contacts at this office.	`175`
Total Employees	Integer	Aggregate employees across all clients serviced by this office.	`4977610`
Total Commissions	Integer	Aggregate commissions for clients at this office, in USD.	`31718980`
Total Carrier Premiums	Integer	Aggregate premiums placed by this office, in USD.	`669505827`
Lead Source	String	Data source attribution. Always `BenefitFlow`.	`BenefitFlow`
Export Date	Date	Snapshot generation date. Format: `M/D/YYYY`.	`4/5/2026`
BenefitFlow User	String	Internal export system user. Always `sftp-export-email`.	`sftp-export-email`
BenefitFlow Broker URL	URL	Direct link to the parent broker in BenefitFlow.	`https://benefit-flow.com/Broker?brokerId=...`
Broker Office ID	String (UUID)	BenefitFlow unique identifier for this office. Primary key.	`0a665d07-558b-5329-...`

Broker Contact

One row per individual contact at a brokerage. Includes professional details, licensing information, the office they are associated with, and aggregated firm-level metrics for the parent brokerage.

Sources: Public profiles, third-party data partners, State Departments of Insurance · Refresh: Weekly (Saturday)

Updated May 14, 2026. Firm-level fields (Headquarters, Total Office Locations, Total Clients, Total Contacts, Total Commissions, Total Carrier Premiums, BenefitFlow Broker URL) were added so that contact records carry the associated brokerage account fields. Five office fields were renamed with the Closest Broker Office prefix to disambiguate them from the new firm-level fields. See SFTP Schema Changes — May 14, 2026 for the full changelog.

Column	Type	Description	Example
Record Type	String	Row type identifier. Always “Broker Contact” in this file.	`Broker Contact`
Contact Full Name	String	Full name of the contact.	`John Feitelberg`
Contact First Name	String	First name.	`John`
Contact Last Name	String	Last name.	`Feitelberg`
Contact LinkedIn URL	String	LinkedIn profile URL (without `https://www.` prefix).	`linkedin.com/in/john-feitelberg-0b025b11`
Contact Email	String	Professional email address.	`john.feitelberg@hubinternational.com`
Contact Mobile Phone 1	String	Mobile phone number in E.164 format.	`+19132193802`
Contact Professional Phone 1	String	Office/work phone number in E.164 format.	`+14079984102`
Contact City	String	City where the contact is located.	`Fall River`
Contact State	String	Two-letter state abbreviation.	`MA`
Contact Job Role	String	Categorized role. Values include: `Executive`, `Producer`, `Account Manager`, `Operations`.	`Executive`
Contact Job Title	String	Full job title.	`President`
Contact Yrs. In Role	Decimal	Number of years in their current role.	`20.5`
Contact Yrs. At Company	Decimal	Number of years at their current company.	`40.1`
License Types	String	Comma-separated insurance license types held.	`Health, Property, Casualty, Life`
NPN Number	String	National Producer Number (insurance license ID). Single-quote prefixed.	`'2852717.00000'`
Carrier Appointments	Integer	Number of active carrier appointments this contact holds.	`272`
Broker Name	String	Name of the brokerage firm this contact works for.	`HUB International`
Broker ID	String (UUID)	BenefitFlow identifier of the parent broker firm. Foreign key → Broker file.	`13234d93-3d22-51e0-...`
Broker Website	String	Broker firm’s website.	`hubinternational.com`
Headquarters	String	City and state of the broker’s headquarters.	`Chicago, IL`
Total Office Locations	Integer	Number of office locations for this broker in BenefitFlow.	`512`
Total Clients	Integer	Number of employer clients associated with this broker.	`18420`
Total Contacts	Integer	Number of individual contacts at this brokerage.	`9876`
Total Commissions	Integer	Aggregate commissions across all clients, in USD.	`725481000`
Total Carrier Premiums	Integer	Aggregate premiums placed across all clients, in USD.	`9854210000`
BenefitFlow Broker URL	URL	Direct link to the broker’s profile in BenefitFlow.	`https://benefit-flow.com/Broker?brokerId=...`
Closest Office ID	String (UUID)	BenefitFlow identifier of the office this contact is associated with. Foreign key → Broker Office file.	`c43272b4-cd28-50c2-...`
Closest Broker Office Name	String	Display name of the associated office.	`"Hub International - Taunton, MA"`
Closest Broker Office Address	String	Full address of the associated office.	`Taunton MA 02780`
Closest Broker Office City	String	City of the associated office.	`Taunton`
Closest Broker Office State	String	State of the associated office.	`MA`
Closest Broker Office Zip	String	ZIP code of the associated office. Single-quote prefixed.	`'02780'`
Lead Source	String	Data source attribution. Always `BenefitFlow`.	`BenefitFlow`
Export Date	Date	Snapshot generation date. Format: `M/D/YYYY`.	`5/16/2026`
Data Last Updated	Date	Date the contact record was last refreshed in BenefitFlow.	`5/14/2026`
BenefitFlow User	String	Internal export system user. Always `sftp-export-email`.	`sftp-export-email`

Employer Contact

One row per individual contact at an employer. Includes professional details, employer association, and aggregated employer-level firmographic and benefits fields for the associated company.

Sources: Public profiles, third-party data partners · Refresh: Weekly (Saturday)

Updated May 14, 2026. Employer-level fields (NAICS, EIN, location, employee counts, funding, lines of business, carriers, renewal dates, primary broker, P&C broker/carrier, PEO, accounting firm, benefits rating, BenefitFlow Employer URL) were added so that contact records carry the associated employer account fields. License Types and NPN Number were removed (not applicable to employer contacts). Five office fields were renamed with the Primary Broker Reported Office prefix to disambiguate them from the new closest-office fields. See SFTP Schema Changes — May 14, 2026 for the full changelog.

Column	Type	Description	Example
Record Type	String	Row type identifier. Always “Employer Contact” in this file.	`Employer Contact`
Contact Full Name	String	Full name of the contact.	`Lorraine Stomski`
Contact First Name	String	First name.	`Lorraine`
Contact Last Name	String	Last name.	`Stomski`
Contact LinkedIn URL	String	LinkedIn profile URL (without `https://www.` prefix).	`linkedin.com/in/lorraine-lo-stomski-8332622`
Contact Email	String	Professional email address.	`lorraine.stomski@walmart.com`
Contact Mobile Phone 1	String	Mobile phone number in E.164 format.	`+14796442094`
Contact Professional Phone 1	String	Office/work phone number in E.164 format.
Contact City	String	City where the contact is located.	`Bentonville`
Contact State	String	Two-letter state abbreviation.	`AR`
Contact Job Role	String	Categorized role. Values include: `Executive`, `HR & Talent`, `Operations`, `Finance`.	`Executive`
Contact Job Title	String	Full job title.	`Chief Talent Officer`
Contact Yrs. In Role	Decimal	Number of years in their current role.	`2`
Contact Yrs. At Company	Decimal	Number of years at their current company.	`9.5`
Employer Name	String	Name of the employer this contact works for.	`Walmart Inc`
Employer ID	String (UUID)	BenefitFlow identifier for the employer. Foreign key → Employer file.	`c86b9d4d-1b87-57dc-...`
Employer Website	String	Employer’s primary website domain.	`walmart.com`
Employer NAICS Description	String	Industry classification.	`Discount Department Stores`
Employer NAICS Code	String	Numeric NAICS code. Single-quote prefixed.	`'452112'`
Employer EIN	String	Federal Employer Identification Number. Single-quote prefixed.	`'710415188'`
Employer City	String	City of the employer’s primary filing location.	`Bentonville`
Employer State	String	Two-letter state abbreviation.	`AR`
Employer Zip Code	String	5-digit ZIP code. Single-quote prefixed.	`'72712'`
Total Employees	Integer	Total number of employees reported by the employer.	`2076632`
Benefit Eligible Employees	Integer	Number of employees eligible for benefits.	`2076632`
Funding	String	Benefits funding model. Values: `Fully-Insured`, `Self-Funded`.	`Self-Funded`
Entity Type	String	Employer plan type. Values: `Single-Employer`, `Multi-Employer`, `Multiple-Employer`.	`Single-Employer`
Line of Business	String	Comma-separated list of benefit lines the employer offers (aggregated across all policies).	`Health, Dental, Vision`
Primary Carrier	String	Insurance carrier with the largest share of this employer’s premiums.	`Kaiser Permanente`
Benefits Renewal Date	String	Month and day when the employer’s benefits renew.	`Jan 1`
Primary Broker	String	Name of the broker with the largest share of this employer’s business.	`Mercer`
Primary Broker Closest Office City	String	City of the broker office geographically closest to the employer.	`Kansas City`
Primary Broker Closest Office State	String	State of the closest broker office.	`MO`
Primary Broker Closest Office Zip	String	ZIP code of the closest broker office. Single-quote prefixed.	`'64108'`
P&C Broker	String	Broker handling the employer’s Property & Casualty insurance.	`Marsh Usa Llc`
P&C Carrier	String	Carrier providing Property & Casualty coverage.	`Federal Insurance Company`
P&C Renewal Date	String	Renewal date for the employer’s Property & Casualty coverage.	`Jan 1`
PEO	String	Professional Employer Organization, if the employer uses one.	`DSH Inc`
Accounting Firm	String	Accounting firm listed on the employer’s 5500 filing.	`Ernst & Young, LLP`
Benefits Rating	Decimal	BenefitFlow-calculated score (0–5) reflecting the richness of the employer’s benefits program.	`4.1`
BenefitFlow Employer URL	URL	Direct link to the employer’s profile in BenefitFlow.	`https://benefit-flow.com/Employer/...`
Primary Broker Reported Office Name	String	Display name of the broker office as reported on the 5500 filing.	`"Mercer - Wilmington, MA"`
Primary Broker Reported Office Address	String	Full address of the reported broker office.	`Wilmington MA 01887`
Primary Broker Reported Office City	String	City of the broker office as reported on the 5500 filing (may differ from closest).	`Wilmington`
Primary Broker Reported Office State	String	State of the reported broker office.	`MA`
Primary Broker Reported Office Zip	String	ZIP code of the reported broker office. Single-quote prefixed.	`'01887'`
Lead Source	String	Data source attribution. Always `BenefitFlow`.	`BenefitFlow`
Export Date	Date	Snapshot generation date. Format: `M/D/YYYY`.	`5/16/2026`
Data Last Updated	Date	Date the contact record was last refreshed in BenefitFlow.	`5/14/2026`
BenefitFlow User	String	Internal export system user. Always `sftp-export-email`.	`sftp-export-email`

Data Delivery Details

Property	Value
Protocol	SFTP over SSH (port 22)
Host	AWS Transfer Family endpoint
Authentication	SSH key-based (no passwords)
File Format	CSV with header row, comma-delimited, double-quote enclosed fields
Character Encoding	UTF-8
Refresh Cadence	Weekly, every Saturday
Retention	~13 rolling weeks of snapshots
File Naming	`TYPE-YYYYMMDD.csv` (e.g., `EMPLOYER-20260405.csv`)
Folder Structure	One folder per entity: `broker/`, `brokerContact/`, `brokerOffices/`, `employer/`, `employerContact/`, `policy/`

For connection setup and SFTP client configuration, see the Bulk Data Access Setup Guide.

Implementation Notes

Quoted fields — always use a CSV parser

Many fields contain commas within values (e.g., Lines of Business, addresses). Always use a proper CSV parser — do not split on commas.

Single-quote prefixed numbers

Fields like EIN, NAICS Code, ZIP Code, and NPN Number are prefixed with a single quote (') to prevent spreadsheet tools from stripping leading zeros. Strip the leading quote during ingestion and treat as strings, not numbers.

ID formats

All BenefitFlow IDs — Employer ID, Broker ID, Broker Office ID, Closest Office ID, Primary Broker ID, and Primary Broker Closest Office ID — are UUIDs (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

One-time ID change (June 2026). Broker, Office, and Contact-Office IDs were previously 32-character hex hashes and were re-keyed to UUIDs. The new values are stable going forward, but they do not match the old hash values. If you cached IDs from a snapshot dated before June 6, 2026, re-pull the current files and re-join — old hash-based joins will return no matches.

Denormalized broker fields

The Policy and Employer files include denormalized broker and office fields for convenience. The Broker and Broker Office files are the canonical source for broker-level data.

Missing-broker values

When no broker is identified for a record, the broker name may show NO Broker and the broker ID field is left blank. Filter these out when analyzing broker relationships. (In snapshots before the June 2026 ID change, the Broker ID was instead populated with the sentinel ffffffffffffffffffffffffffffffff — treat that legacy value the same as blank.)

Constant fields

Record Type, Lead Source, and BenefitFlow User contain the same value for every row in a given file. They exist for system compatibility and can be safely ignored during analysis.

Closest Office vs. Reported Office

Two broker office locations appear on Employer and Policy records. Closest Office is the BenefitFlow-determined office nearest to the employer. Reported Office is the office listed on the original Form 5500 filing. These often differ — the filing may reference a headquarters while the closest office reflects the local servicing branch.

Salesforce Integration

HubSpot Integration

Dynamics Integration

Bulk Data (SFTP)

Overview

Entity Relationships

Join Keys

Key Relationships

Employer

Policy

Broker

Broker Office

Broker Contact

Employer Contact

Data Delivery Details

Implementation Notes

​Overview

​Entity Relationships

​Join Keys

​Key Relationships

​Employer

​Policy

​Broker

​Broker Office

​Broker Contact

​Employer Contact

​Data Delivery Details

​Implementation Notes

Overview

Entity Relationships

Join Keys

Key Relationships

Employer

Policy

Broker

Broker Office

Broker Contact

Employer Contact

Data Delivery Details

Implementation Notes