# Book of Business Field Reference (/docs/guides/reference/book-of-business-fields)
This is the full field and matching reference for getting your book of
business into careCycle. For the step-by-step walkthrough, see [Import Your
Book of Business](/docs/guides/getting-set-up/import-your-book-of-business).
Everything works as an **upsert**: if a matching record is already there, it
gets updated, and if not, a new one is created. What counts as "matching"
depends on how the data comes in, so CSV imports and API syncs are split out
below.
How Matching Works [#how-matching-works]
This is **Settings > CRM Settings > Import Contacts**, whether you map the
columns yourself or use the import assistant.
**Customers** are matched by **phone number**. Nothing else (MBI, your
system's ID, name, or date of birth) is used to match a customer on a CSV.
So if a member's phone number changed since your last import, you'll get a
second record.
**Policies** are matched in two passes:
1. **IDs first.** careCycle checks every policy ID you sent:
`carrierAssignedPolicyId`, `ffmApplicationId`, `policyNumber`,
`applicationId`, `healthSherpaPolicyId`, and `sunFireEnrollmentCode`.
The carrier's policy ID is checked against both `carrierAssignedPolicyId`
and `policyNumber`, since exports put it in either one. If the IDs point
at more than one policy, or disagree with each other, that row's policy
is skipped rather than guessed.
2. **Then content.** `policyType` + `planCode` + `effectiveDate`. If one of
the last two is missing, `policyType` + `planCode` or `policyType` +
`effectiveDate`.
For ACA, if you sent a policy ID and nothing matched it, careCycle creates
a new policy instead of falling back to the content match.
**Customer matching**
1. `mbiNumber` first (dashes and capitalization don't matter).
2. `firstName` + `lastName` + `dateOfBirth` + `phoneNumber` if there's no
MBI match. If a customer matches this way, their MBI gets updated.
**Policy matching**
1. `sunFireEnrollmentCode` first, if you sent one.
2. `planCode` + `effectiveDate` if there's no SunFire match.
When a new policy is created, any of that customer's existing policies of
the **same policy type** with an effective date more than a year ago are
automatically terminated.
**Customer matching**
1. `healthSherpaCustomerId`
2. `externalId` (your system's customer ID)
3. `carrierAssignedCustomerId`
4. `firstName` + `lastName` + `dateOfBirth` + `phoneNumber`
**Policy matching**
1. `healthSherpaPolicyId`
2. `carrierAssignedPolicyId`
When a new policy is created, any of that customer's existing policies
with an effective date more than a year ago are automatically terminated.
`policyType` is always set to ACA.
Medicare Plan Codes [#medicare-plan-codes]
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).
CSV Import Options [#csv-import-options]
A few settings only exist when you import a CSV:
* **Customer status** (required for every import): **Lead** (new potential
customer), **Active** (customer with active coverage), or **Inactive**
(legacy customer without active coverage).
* **Policy type**: if your file has policy columns but no `policyType`
column, you pick one for the whole file. You can also set a **Fallback
policy type** for rows that leave it blank.
* **Add to campaign (optional)**: adds everyone in the file to a campaign.
Only do this with a campaign that's already active. See [Add Customers to a
Campaign](/docs/guides/campaign-toolkit/add-customers-to-a-campaign).
* **Resolve Data Warnings**: set default values for fields that are missing.
* Files can be up to 100MB.
The only column a CSV strictly needs is the phone number. The required
fields below are what the API syncs require, and what you'll want in your CSV
anyway.
Required Fields [#required-fields]
Customer 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 [#medicare-customer-fields]
| Field | Format | Example |
| ----------- | ------------------------------- | ------------- |
| `mbiNumber` | Medicare Beneficiary Identifier | 1EG4-TE5-MK73 |
TCPA Compliance Fields [#tcpa-compliance-fields]
At least one of these needs to be on every record. Without a time zone or
postal code, we can't tell what time it is for the member, so campaigns skip
them.
| Field | Format | Example |
| ------------ | ------------------------------ | --------------- |
| `postalCode` | 5 digits | 60614 |
| `timezone` | IANA time zone or abbreviation | America/Chicago |
Medicare Policy Fields [#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, MM-DD-YYYY, or YYYY-MM-DD | 01/01/2026 |
| `enrollmentDate` | MM/DD/YYYY, MM-DD-YYYY, or YYYY-MM-DD | 10/22/2025 |
| `aorNpn` | Agent of Record NPN, max 50 characters | 8245019 |
| `writingAgentNpn` | Writing Agent NPN, max 50 characters | 8245019 |
ACA Policy Fields [#aca-policy-fields]
The ACA sync sets `policyType` to ACA for you. On a CSV, include a
`policyType` column or pick ACA as the file's policy type when you import.
| 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, MM-DD-YYYY, or YYYY-MM-DD | 01/01/2026 |
| `enrollmentDate` | MM/DD/YYYY, MM-DD-YYYY, or YYYY-MM-DD | 12/10/2025 |
| `aorNpn` | Agent of Record NPN, max 50 characters | 8245019 |
| `writingAgentNpn` | Writing Agent NPN, max 50 characters | 8245019 |
Recommended Optional Fields [#recommended-optional-fields]
You don't have to send these, but you really should. They make your
campaigns smarter, your task automations more useful, and give Cora more to
work with on a call.
* **Customer details:** `externalId`, `email`, `dateOfBirth`, `address`,
`city`, `state`, `language`
* **Communication preferences:** `doNotCall`, `doNotSMS`, `doNotEmail`,
`doNotMail`
* **Policy details:** `policySubType`, `policyNumber`, `applicationId`,
`status` (see [Policy Statuses](#policy-statuses)), `electionPeriod`,
`writtenAs`
* **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 [#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 [#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 [#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 for you. Contacts marked do-not-call
or do-not-SMS are automatically kept out of future campaign calls or texts.
Policy Statuses [#policy-statuses]
`status` takes one of these values. Statuses drive a lot: automations like
[Win-Backs and Rapid Disenrollment
Save](/docs/guides/keep-your-members/save-cancelling-members) fire when a
policy's status changes, and campaign filters use them too. See [Automation
Triggers and Filters](/docs/guides/reference/automation-triggers-and-filters).
| Status | What it means |
| ------------------------ | --------------------------------------------------------------- |
| **Active** | In force |
| **Placed** | Issued by the carrier, not in force yet (future effective date) |
| **Pending** | Submitted, waiting on the carrier |
| **Pending Effectuation** | Enrolled, not active yet |
| **Pending Followup** | Needs something from the member (like DMI or verification) |
| **Suspended** | Grace period or temporary non-payment |
| **Cancelled** | The member ended it |
| **Terminated** | The carrier ended it |
| **Future Cancel** | Scheduled to end (for example, an AOR change) |
| **Deceased** | The member passed away |
| **Not Approved** | The application was denied |
Other Accepted Values [#other-accepted-values]
| Field | Accepted values |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `policyType` | MA, MAPD, PDP, MS, ACA, LTC, Individual Health, FE, Annuity, Life, Dental, Vision, Hospital Indemnity, Cancer, Critical Illness, Accident, Group, Home Health Care |
| `electionPeriod` | IEP, AEP, OEP, SEP, ICEP, MA-OEP |
| `writtenAs` | New Business, Like Plan Change, Unlike Plan Change, Reinstatement, Rewrite |
| `metalLevel` | Catastrophic, Bronze, Expanded Bronze, Silver, Gold, Platinum |
| `exchangeStatus` | FFM, SBM, SBM FP, OFF EXCHANGE, PRIVATE EXCHANGE, UNKNOWN |
The Medicare API sync only accepts MA, MAPD, MS, and PDP, and the ACA sync
only ACA. CSV imports take any policy type.
More Fields You Can Import [#more-fields-you-can-import]
The importer accepts a lot more than the fields above. A few worth knowing:
* **More customer details:** `middleName`, `preferredName`, `suffix`,
`salutation`, `gender`, `address2`, `county`, `ethnicity`
* **Medicare and Medicaid:** `medicarePartADate`, `medicarePartBDate`,
`medicareCard`, `medicaid`, `medicaidNumber`
* **Current coverage:** `existingCoverage`, `existingCoverageCarrier`,
`existingCoveragePlanName`
* **Household and income (ACA):** `householdIncome`, `filingStatus`,
`dependentCount`, `annualIncome`, `subsidyEligible`,
`desiredCoverageStartDate`
* **Other:** `veteran`, `vaNumber`, `agentName`, `agentNpn`
* **Policy IDs:** `carrierAssignedPolicyId`, `ffmApplicationId`,
`sunFireEnrollmentCode`, `healthSherpaPolicyId`
Anything that doesn't have a standard field can go into a [custom
field](/docs/guides/reference/custom-fields), for customers or policies.
Full Sync Field Coverage [#full-sync-field-coverage]
For complete sync field coverage via the API, see:
* [Medicare Sync](/docs/api-reference/sync/sync-medicare-customers-and-policies)
* [ACA Sync](/docs/api-reference/sync/sync-aca-customers-and-policies)
The step-by-step import walkthrough that uses this reference.
Choose between CSV re-imports and an ongoing CRM sync.
Sync ACA customers and policies straight from HealthSherpa.