CAcarecycle
Customers.Policies

Create customer policy

Add an insurance policy to a customer's record.

Medicare plan codes: For MA and MAPD, planCode must be a CMS contract-style code starting with H or R. For PDP, it must start with S, H, R, E, or X. The three-digit segment is optional: send contract+plan only (H3146-036) and careCycle infers the segment from CMS reference data, defaulting to -000 for non-segmented plans; a record is rejected only when the plan genuinely has multiple segments (include the segment to disambiguate). Dashes are optional in requests (H1234001000 and H1234-001-000 are accepted); careCycle stores the canonical dashed form. MS plan codes are carrier-specific and are not required to follow the CMS contract format.

post/v2/customers/{id}/policies

Request

  • Base URL
    https://api.carecycle.ai
  • URL
    https://api.carecycle.ai/v2/customers/{id}/policies
  • Auth
    API key in header x-api-key

Path parameters

idstring uuid required

Customer ID

Request body

createdBystring uuid nullable
updatedBystring uuid nullable
policyType'MA' | 'MAPD' | 'PDP' | 'MS' | 'ACA' | 'LTC' | 'Individual Health' | 'FE' | 'Annuity' | 'Life' | 'Dental' | 'Vision' | 'Hospital Indemnity' | 'Cancer' | 'Critical Illness' | 'Accident' | 'Group' | 'Home Health Care' | 'International Travel' required
policySubTypestring nullable
policyNumberstring nullable
applicationIdstring nullable
carrierIdstring uuid nullable
carrierNamestring nullable

Insurance carrier name. Resolved against the canonical carrier list at https://api.carecycle.ai/v2/carriers; accepts any carrier displayName or registered alias (e.g. 'UHC', 'BCBSIL', 'Cigna Health and Life Insurance Company'). Generic 'BCBS' / 'Blue Cross Blue Shield' inputs are disambiguated to the correct state plan using the customer's state.

planNamestring nullable

Name of the policy

planCodestring nullable

Plan code of the policy

carrierAssignedPolicyIdstring nullable
healthSherpaPolicyIdstring nullable
sunFireEnrollmentCodestring nullable
connectureConfirmationNumberstring nullable
hiosIdstring nullable
metalLevel'Catastrophic' | 'Bronze' | 'Expanded Bronze' | 'Silver' | 'Gold' | 'Platinum' | 'null' nullable
status'Active' | 'Placed' | 'Pending' | 'Pending Effectuation' | 'Pending Followup' | 'Suspended' | 'Cancelled' | 'Terminated' | 'Future Cancel' | 'Deceased' | 'Not Approved' | 'null' nullable

The current status of the policy

applicationApprovalDatestring date nullable

Application approval date. Canonical format: YYYY-MM-DD

effectiveDatestring date nullable

Policy effective date. Canonical format: YYYY-MM-DD

terminationDatestring date nullable

Policy termination date. Canonical format: YYYY-MM-DD

renewalDatestring date nullable

Policy renewal date. Canonical format: YYYY-MM-DD

enrollmentDatestring date nullable

Policy enrollment date. Canonical format: YYYY-MM-DD

cancelledDatestring date nullable

Policy cancellation date. Canonical format: YYYY-MM-DD

declineReasonstring nullable
declineReasonDescriptionstring nullable
cancellationReasonstring nullable
cancellationReasonDescriptionstring nullable
electionPeriod'IEP' | 'AEP' | 'OEP' | 'SEP' | 'ICEP' | 'MA-OEP' | 'null' nullable
gracePeriodStartDatestring date nullable

Grace period start date. Canonical format: YYYY-MM-DD

paidThroughDatestring date nullable

Coverage paid-through date. Canonical format: YYYY-MM-DD

ffmApplicationIdstring nullable
ffmSubscriberIdstring nullable
aorAgentIdstring uuid nullable
aorFirstNamestring nullable

Agent Of Record First Name

aorLastNamestring nullable

Agent Of Record Last Name

aorNpnstring nullable

Agent Of Record NPN

writingAgentNpnstring nullable
writingAgentNamestring nullable
sepTypestring nullable
sepCodestring nullable
sepStartDatestring date nullable

SEP start date. Canonical format: YYYY-MM-DD

sepEndDatestring date nullable

SEP end date. Canonical format: YYYY-MM-DD

sepDocumentationReceivedboolean nullable
sepDocumentationDatestring date nullable

SEP documentation date. Canonical format: YYYY-MM-DD

sepNotesstring nullable
monthlyPremiumstring nullable
deductiblestring nullable
outOfPocketMaxstring nullable
subsidyAmountstring nullable
usingSubsidyboolean nullable
premiumMode'Monthly' | 'Quarterly' | 'Semi-Annual' | 'Annual' | 'null' nullable
paymentMode'ACH' | 'Credit/ debit card' | 'Direct bill' | 'null' nullable
paymentMethod'Credit Card' | 'Debit Card' | 'Check' | 'ACH / Bank Draft' | 'Money Order' | 'Cash' | 'Other' | 'null' nullable
grossPremiumstring nullable
netPremiumstring nullable
initialCommissionstring nullable
renewalCommissionstring nullable
spifAmountstring nullable
policyLivesinteger nullable

Number of lives covered by the policy

wasAgentboolean nullable
writtenAs'New Business' | 'Like Plan Change' | 'Unlike Plan Change' | 'Reinstatement' | 'Rewrite' | 'null' nullable
isReplacingstring nullable
isRewriteboolean nullable
hospitalNetworkstring nullable
pcpNetworkstring nullable
ssbciVerificationRequiredboolean nullable
dailyBenefitstring nullable
eliminationPeriodinteger nullable
benefitPeriodinteger nullable
hasColaboolean nullable
deathBenefitstring nullable
terminteger nullable
maturityDatestring date nullable

Policy maturity date. Canonical format: YYYY-MM-DD

ridersstring nullable
coverageLevel'Immediate' | 'Graded/ROP' | 'Modified Level' | 'Standard Level' | 'Preferred Level' | 'null' nullable
draftDayinteger nullable

Day of the month the premium drafts (1-31). Not a calendar date.

exchangeStatus'FFM' | 'SBM' | 'SBM FP' | 'OFF EXCHANGE' | 'PRIVATE EXCHANGE' | 'UNKNOWN' | 'null' nullable
billingMethodstring nullable
benefitReminderstring date nullable

Benefit reminder date. Canonical format: YYYY-MM-DD

surveyCompletedboolean nullable
reasonForPurchasestring nullable
policyNotesstring nullable
callHistoryIdstring uuid

Optional source call context

Example request

{
  "carrierName": "Aetna",
  "planName": "Medicare Elite",
  "planCode": "H1290-036-001",
  "aorFirstName": "John",
  "aorLastName": "Doe",
  "aorNpn": "123456789",
  "policyLives": 3,
  "draftDay": 1
}

Response

POST /v2/customers/:id/policies Positive response

idstring uuid required
createdAtstring date-time nullable required

Policy creation time. ISO 8601 timestamp

createdBystring uuid nullable required
updatedAtstring date-time nullable required

Policy last update time. ISO 8601 timestamp

updatedBystring uuid nullable required
customerIdstring uuid required
policyType'MA' | 'MAPD' | 'PDP' | 'MS' | 'ACA' | 'LTC' | 'Individual Health' | 'FE' | 'Annuity' | 'Life' | 'Dental' | 'Vision' | 'Hospital Indemnity' | 'Cancer' | 'Critical Illness' | 'Accident' | 'Group' | 'Home Health Care' | 'International Travel' required
policySubTypestring nullable required
policyNumberstring nullable required
applicationIdstring nullable required
carrierIdstring uuid nullable required
carrierNamestring nullable required
planNamestring nullable required
planCodestring nullable required
carrierAssignedPolicyIdstring nullable required
healthSherpaPolicyIdstring nullable required
sunFireEnrollmentCodestring nullable required
connectureConfirmationNumberstring nullable required
hiosIdstring nullable required
metalLevel'Catastrophic' | 'Bronze' | 'Expanded Bronze' | 'Silver' | 'Gold' | 'Platinum' | 'null' nullable required
status'Active' | 'Placed' | 'Pending' | 'Pending Effectuation' | 'Pending Followup' | 'Suspended' | 'Cancelled' | 'Terminated' | 'Future Cancel' | 'Deceased' | 'Not Approved' | 'null' nullable required
applicationApprovalDatestring date nullable required

Application approval date. Canonical format: YYYY-MM-DD

effectiveDatestring date nullable required

Policy effective date. Canonical format: YYYY-MM-DD

terminationDatestring date nullable required

Policy termination date. Canonical format: YYYY-MM-DD

renewalDatestring date nullable required

Policy renewal date. Canonical format: YYYY-MM-DD

enrollmentDatestring date nullable required

Policy enrollment date. Canonical format: YYYY-MM-DD

cancelledDatestring date nullable required

Policy cancellation date. Canonical format: YYYY-MM-DD

declineReasonstring nullable required
declineReasonDescriptionstring nullable required
cancellationReasonstring nullable required
cancellationReasonDescriptionstring nullable required
electionPeriod'IEP' | 'AEP' | 'OEP' | 'SEP' | 'ICEP' | 'MA-OEP' | 'null' nullable required
gracePeriodStartDatestring date nullable required

Grace period start date. Canonical format: YYYY-MM-DD

paidThroughDatestring date nullable required

Coverage paid-through date. Canonical format: YYYY-MM-DD

ffmApplicationIdstring nullable required
ffmSubscriberIdstring nullable required
aorAgentIdstring uuid nullable required
aorFirstNamestring nullable required
aorLastNamestring nullable required
aorNpnstring nullable required
writingAgentNpnstring nullable required
writingAgentNamestring nullable required
sepTypestring nullable required
sepCodestring nullable required
sepStartDatestring date nullable required

SEP start date. Canonical format: YYYY-MM-DD

sepEndDatestring date nullable required

SEP end date. Canonical format: YYYY-MM-DD

sepDocumentationReceivedboolean nullable required
sepDocumentationDatestring date nullable required

SEP documentation date. Canonical format: YYYY-MM-DD

sepNotesstring nullable required
monthlyPremiumstring nullable required
deductiblestring nullable required
outOfPocketMaxstring nullable required
subsidyAmountstring nullable required
usingSubsidyboolean nullable required
premiumMode'Monthly' | 'Quarterly' | 'Semi-Annual' | 'Annual' | 'null' nullable required
paymentMode'ACH' | 'Credit/ debit card' | 'Direct bill' | 'null' nullable required
paymentMethod'Credit Card' | 'Debit Card' | 'Check' | 'ACH / Bank Draft' | 'Money Order' | 'Cash' | 'Other' | 'null' nullable required
grossPremiumstring nullable required
netPremiumstring nullable required
initialCommissionstring nullable required
renewalCommissionstring nullable required
spifAmountstring nullable required
policyLivesinteger nullable required
wasAgentboolean nullable required
writtenAs'New Business' | 'Like Plan Change' | 'Unlike Plan Change' | 'Reinstatement' | 'Rewrite' | 'null' nullable required
isReplacingstring nullable required
isRewriteboolean nullable required
hospitalNetworkstring nullable required
pcpNetworkstring nullable required
ssbciVerificationRequiredboolean nullable required
dailyBenefitstring nullable required
eliminationPeriodinteger nullable required
benefitPeriodinteger nullable required
hasColaboolean nullable required
deathBenefitstring nullable required
terminteger nullable required
maturityDatestring date nullable required

Policy maturity date. Canonical format: YYYY-MM-DD

ridersstring nullable required
coverageLevel'Immediate' | 'Graded/ROP' | 'Modified Level' | 'Standard Level' | 'Preferred Level' | 'null' nullable required
draftDayinteger nullable required
exchangeStatus'FFM' | 'SBM' | 'SBM FP' | 'OFF EXCHANGE' | 'PRIVATE EXCHANGE' | 'UNKNOWN' | 'null' nullable required
billingMethodstring nullable required
benefitReminderstring date nullable required

Benefit reminder date. Canonical format: YYYY-MM-DD

surveyCompletedboolean nullable required
reasonForPurchasestring nullable required
policyNotesstring nullable required

Changes

No recorded changes to this operation across all 2 revisions of this API.