Book of Business Field Reference

Every field, format, and matching rule for Medicare and ACA customer and policy imports.

This is the complete field and matching reference for book of business imports and syncs. For the step-by-step import walkthrough, see Import Your Book of Business.

careCycle uses upsert logic for all imports and syncs: if a matching record already exists, it gets updated; if not, a new record is created.

Medicare Matching

Customer matching cascade

mbiNumber is checked first as the primary identifier.
lastName + dateOfBirth + phoneNumber is used as the fallback if there is no MBI match. The MBI is updated on the record if matched this way.

Policy matching cascade

sunFireEnrollmentCode is checked first if present.
planCode + effectiveDate is used as the fallback if there is no SunFire code match.

Medicare plan code rules

For Medicare Advantage and Part D policies, planCode should be a CMS contract-style code. Dashes are optional in the import or sync payload, and careCycle stores the canonical dashed form.

`policyType`	Accepted contract prefixes	Accepted examples	Stored as
`MA` / `MAPD`	`H` or `R`	`H1234-001-000`, `H1234001000`, `H1234-001`	`H1234-001-000`
`PDP`	`S`, `H`, `R`, `E`, or `X`	`S1234-001-000`, `S1234001000`, `S1234-001`	`S1234-001-000`
`MS`	Carrier-specific	`Plan G`, `Aetna Plan N`	Stored as provided, except trailing `-null` cleanup

For Medicare Advantage and Part D, the final three-digit segment is optional. If you send contract+plan only (for example H3146-036), careCycle infers the segment from CMS reference data and stores the complete code: it uses the plan's only segment when there is exactly one, defaults to -000 for a non-segmented plan, and rejects the record only when the plan has multiple segments (in which case include the segment to disambiguate).

ACA Matching

Customer matching cascade

healthSherpaCustomerId
externalId, meaning your system's customer ID
carrierAssignedCustomerId
lastName + dateOfBirth + phoneNumber

Policy matching cascade

healthSherpaPolicyId
carrierAssignedPolicyId

For ACA, when a new policy is created, any existing policies for that customer with an effective date more than one year ago are automatically terminated.

Required Fields

Customer Fields

These fields are required for all books.

Field	Format	Example
`firstName`	1-255 characters	Margaret
`lastName`	1-255 characters	Thompson
`phoneNumber`	`+1XXXXXXXXXX`, `XXXXXXXXXX`, or `(XXX) XXX-XXXX`	+13125551234

Medicare Customer Fields

Field	Format	Example
`mbiNumber`	Medicare Beneficiary Identifier	1EG4-TE5-MK73

TCPA Compliance Fields

At least one of these must be present on every record. Without a time zone or postal code, outbound campaigns will not fire for that contact.

Field	Format	Example
`postalCode`	5 digits	60614
`timezone`	IANA time zone or abbreviation	America/Chicago

Medicare Policy Fields

Field	Format	Example
`policyType`	MA, MAPD, MS, or PDP	MAPD
`carrierName`	1-255 characters	Humana
`planName`	1-255 characters	Humana Gold Plus HMO
`planCode`	CMS contract-style code for `MA`, `MAPD`, and `PDP`; carrier-specific for `MS`	H1036-228
`effectiveDate`	MM/DD/YYYY or MM-DD-YYYY	01/01/2026
`enrollmentDate`	MM/DD/YYYY or MM-DD-YYYY	10/22/2025
`aorNpn`	Agent of Record NPN, max 50 characters	8245019
`writingAgentNpn`	Writing Agent NPN, max 50 characters	8245019

ACA Policy Fields

policyType is automatically set to ACA on import. No policyType column is needed.

Field	Format	Example
`carrierName`	Max 255 characters	Blue Shield of California
`planName`	Max 255 characters	Blue Shield Silver 70 PPO
`planCode`	Max 255 characters	93689CA0620004
`effectiveDate`	MM/DD/YYYY or MM-DD-YYYY	01/01/2026
`enrollmentDate`	MM/DD/YYYY or MM-DD-YYYY	12/10/2025
`aorNpn`	Agent of Record NPN, max 50 characters	8245019
`writingAgentNpn`	Writing Agent NPN, max 50 characters	8245019

Recommended Optional Fields

Including these is highly recommended. They unlock more capable campaigns, better task automations, and richer member context for Cora.

Customer details: externalId, email, dateOfBirth, address, city, state, language
Communication preferences: doNotCall, doNotSMS, doNotEmail, doNotMail
Policy details: policySubType, policyNumber, applicationId, status, electionPeriod
ACA-specific: exchangeStatus, metalLevel, usingSubsidy, subsidyAmount, grossPremium, netPremium, paidThroughDate, gracePeriodStartDate, healthSherpaPolicyId
Commission and financial: monthlyPremium, deductible, outOfPocketMax, initialCommission, renewalCommission, policyLives

Communication preferences are enforced natively. Contacts marked do-not-call or do-not-SMS are automatically suppressed from future campaigns.