Create customer policy
Create a new policy for a customer.
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.
Authorization
x-api-key API key required for authentication.
Keys begin with 'cc_' prefix. Get your API key from the Developer Dashboard.
In: header
Path Parameters
Customer ID
Request Body
application/json
POST /v2/customers/:id/policies Request body
TypeScript Definitions
Use the request body type in TypeScript.
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.
Name of the policy
Plan code of the policy
The current status of the policy
Application approval date. Canonical format: YYYY-MM-DD
Policy effective date. Canonical format: YYYY-MM-DD
Policy termination date. Canonical format: YYYY-MM-DD
Policy renewal date. Canonical format: YYYY-MM-DD
Policy enrollment date. Canonical format: YYYY-MM-DD
Policy cancellation date. Canonical format: YYYY-MM-DD
Grace period start date. Canonical format: YYYY-MM-DD
Coverage paid-through date. Canonical format: YYYY-MM-DD
Agent Of Record First Name
Agent Of Record Last Name
Agent Of Record NPN
SEP start date. Canonical format: YYYY-MM-DD
SEP end date. Canonical format: YYYY-MM-DD
SEP documentation date. Canonical format: YYYY-MM-DD
Number of lives covered by the policy
Policy maturity date. Canonical format: YYYY-MM-DD
Benefit reminder date. Canonical format: YYYY-MM-DD
Optional source call context
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.carecycle.ai/v2/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08/policies" \ -H "Content-Type: application/json" \ -d '{ "carrierName": "Aetna", "planName": "Medicare Elite", "planCode": "H1290-036-001", "aorFirstName": "John", "aorLastName": "Doe", "aorNpn": "123456789", "policyLives": 3 }'{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "2019-08-24T14:15:22Z",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"updatedAt": "2019-08-24T14:15:22Z",
"updatedBy": "b0efe45f-0520-4e21-90f0-7e35f137732e",
"customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
"policyType": "MA",
"policySubType": "string",
"policyNumber": "string",
"applicationId": "string",
"carrierId": "81a9910c-2657-4f54-9feb-7f6d85d613bc",
"carrierName": "string",
"planName": "string",
"planCode": "string",
"carrierAssignedPolicyId": "string",
"healthSherpaPolicyId": "string",
"sunFireEnrollmentCode": "string",
"connectureConfirmationNumber": "string",
"hiosId": "string",
"metalLevel": "Catastrophic",
"status": "Active",
"applicationApprovalDate": "2019-08-24",
"effectiveDate": "2019-08-24",
"terminationDate": "2019-08-24",
"renewalDate": "2019-08-24",
"enrollmentDate": "2019-08-24",
"cancelledDate": "2019-08-24",
"declineReason": "string",
"declineReasonDescription": "string",
"cancellationReason": "string",
"cancellationReasonDescription": "string",
"electionPeriod": "IEP",
"gracePeriodStartDate": "2019-08-24",
"paidThroughDate": "2019-08-24",
"ffmApplicationId": "string",
"ffmSubscriberId": "string",
"aorAgentId": "b69824d9-b3c3-46ff-b624-5d3573bdf8fa",
"aorFirstName": "string",
"aorLastName": "string",
"aorNpn": "string",
"writingAgentNpn": "string",
"writingAgentName": "string",
"sepType": "string",
"sepCode": "string",
"sepStartDate": "2019-08-24",
"sepEndDate": "2019-08-24",
"sepDocumentationReceived": true,
"sepDocumentationDate": "2019-08-24",
"sepNotes": "string",
"monthlyPremium": "string",
"deductible": "string",
"outOfPocketMax": "string",
"subsidyAmount": "string",
"usingSubsidy": true,
"premiumMode": "Monthly",
"paymentMode": "ACH",
"paymentMethod": "Credit Card",
"grossPremium": "string",
"netPremium": "string",
"initialCommission": "string",
"renewalCommission": "string",
"spifAmount": "string",
"policyLives": -2147483648,
"wasAgent": true,
"writtenAs": "New Business",
"isReplacing": "string",
"isRewrite": true,
"hospitalNetwork": "string",
"pcpNetwork": "string",
"ssbciVerificationRequired": true,
"dailyBenefit": "string",
"eliminationPeriod": -2147483648,
"benefitPeriod": -2147483648,
"hasCola": true,
"deathBenefit": "string",
"term": -2147483648,
"maturityDate": "2019-08-24",
"riders": "string",
"exchangeStatus": "FFM",
"billingMethod": "string",
"benefitReminder": "2019-08-24",
"surveyCompleted": true,
"reasonForPurchase": "string",
"policyNotes": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "VALIDATION_ERROR",
"errors": [
{
"path": [
"string"
],
"message": "string",
"expected": "string",
"received": "string",
"code": "string"
}
],
"failedRecords": [
{
"index": 0,
"phoneNumber": "string",
"firstName": "string",
"lastName": "string",
"externalId": "string"
}
]
}{
"message": "string",
"code": "string",
"retryAfter": 0
}{
"message": "string",
"code": "string"
}