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
Ancillary premium payments: premiumMode, paymentMode, paymentMethod
Underwriting (life and final expense): heightInches, weightPounds, smokerStatus
Final expense and life policy details: deathBenefit, coverageLevel, draftDay, term, maturityDate, riders

Underwriting Fields

Carriers ask for these on life and final expense applications. Supplying them up front means an agent does not have to collect them mid-call.

Field	Type	Notes
`heightInches`	integer	Total height in inches, so 6'0" is `72`. Not a formatted string.
`weightPounds`	integer	Pounds.
`smokerStatus`	boolean	Omit or send `null` when unknown. `false` means confirmed non-smoker, which is not the same answer as unknown.

Final Expense Policy Fields

Field	Accepted values	Example
`deathBenefit`	decimal string	`25000.00`
`coverageLevel`	Immediate, Graded/ROP, Modified Level, Standard Level, Preferred Level	Immediate
`draftDay`	integer 1 to 31	`15`

deathBenefit is the field agents often call "face value"; there is one field for both names. draftDay is the day of the month the premium drafts, not a date. Coverage level names carry age bands at most carriers (Immediate and Graded/ROP typically apply to ages 0 to 79); the field stores the level only.

Ancillary Premium Payment Fields

These fields apply to policy types outside MA, MAPD, PDP, MS, and ACA.

Field	Accepted values	Example
`premiumMode`	Monthly, Quarterly, Semi-Annual, Annual	Monthly
`paymentMode`	ACH, Credit/ debit card, Direct bill	ACH
`paymentMethod`	Credit Card, Debit Card, Check, ACH / Bank Draft, Money Order, Cash, Other	ACH / Bank Draft

CSV imports normalize common capitalization and formatting variants to these canonical values. API requests must use one of the accepted values shown above.

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