---
title: "Update customer policy"
method: PATCH
path: "/v2/customers/{id}/policies/{policyId}"
tags: ["Customers.Policies"]
---

# Update customer policy

`PATCH /v2/customers/{id}/policies/{policyId}`

## Request

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

Change a policy on a customer's record.

## Path parameters

- `id` string, uuid, required: Customer ID
- `policyId` string, uuid, required: Policy ID

## Request body

- PatchV2CustomersIdPoliciesPolicyIdRequestBody
  - `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'
  - `policySubType` string, nullable
  - `policyNumber` string, nullable
  - `applicationId` string, nullable
  - `carrierId` string, uuid, nullable
  - `carrierName` string, nullable
  - `planName` string, nullable
  - `planCode` string, nullable
  - `carrierAssignedPolicyId` string, nullable
  - `healthSherpaPolicyId` string, nullable
  - `sunFireEnrollmentCode` string, nullable
  - `connectureConfirmationNumber` string, nullable
  - `hiosId` string, 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
  - `applicationApprovalDate` string, date, nullable: Application approval date. Canonical format: YYYY-MM-DD
  - `effectiveDate` string, date, nullable: Policy effective date. Canonical format: YYYY-MM-DD
  - `terminationDate` string, date, nullable: Policy termination date. Canonical format: YYYY-MM-DD
  - `renewalDate` string, date, nullable: Policy renewal date. Canonical format: YYYY-MM-DD
  - `enrollmentDate` string, date, nullable: Policy enrollment date. Canonical format: YYYY-MM-DD
  - `cancelledDate` string, date, nullable: Policy cancellation date. Canonical format: YYYY-MM-DD
  - `declineReason` string, nullable
  - `declineReasonDescription` string, nullable
  - `cancellationReason` string, nullable
  - `cancellationReasonDescription` string, nullable
  - `electionPeriod` 'IEP' | 'AEP' | 'OEP' | 'SEP' | 'ICEP' | 'MA-OEP' | 'null', nullable
  - `gracePeriodStartDate` string, date, nullable: Grace period start date. Canonical format: YYYY-MM-DD
  - `paidThroughDate` string, date, nullable: Coverage paid-through date. Canonical format: YYYY-MM-DD
  - `ffmApplicationId` string, nullable
  - `ffmSubscriberId` string, nullable
  - `aorAgentId` string, uuid, nullable
  - `aorFirstName` string, nullable
  - `aorLastName` string, nullable
  - `aorNpn` string, nullable
  - `writingAgentNpn` string, nullable
  - `writingAgentName` string, nullable
  - `sepType` string, nullable
  - `sepCode` string, nullable
  - `sepStartDate` string, date, nullable: SEP start date. Canonical format: YYYY-MM-DD
  - `sepEndDate` string, date, nullable: SEP end date. Canonical format: YYYY-MM-DD
  - `sepDocumentationReceived` boolean, nullable
  - `sepDocumentationDate` string, date, nullable: SEP documentation date. Canonical format: YYYY-MM-DD
  - `sepNotes` string, nullable
  - `monthlyPremium` string, nullable
  - `deductible` string, nullable
  - `outOfPocketMax` string, nullable
  - `subsidyAmount` string, nullable
  - `usingSubsidy` boolean, 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
  - `grossPremium` string, nullable
  - `netPremium` string, nullable
  - `initialCommission` string, nullable
  - `renewalCommission` string, nullable
  - `spifAmount` string, nullable
  - `policyLives` integer, nullable
  - `wasAgent` boolean, nullable
  - `writtenAs` 'New Business' | 'Like Plan Change' | 'Unlike Plan Change' | 'Reinstatement' | 'Rewrite' | 'null', nullable
  - `isReplacing` string, nullable
  - `isRewrite` boolean, nullable
  - `hospitalNetwork` string, nullable
  - `pcpNetwork` string, nullable
  - `ssbciVerificationRequired` boolean, nullable
  - `dailyBenefit` string, nullable
  - `eliminationPeriod` integer, nullable
  - `benefitPeriod` integer, nullable
  - `hasCola` boolean, nullable
  - `deathBenefit` string, nullable
  - `term` integer, nullable
  - `maturityDate` string, date, nullable: Policy maturity date. Canonical format: YYYY-MM-DD
  - `riders` string, nullable
  - `coverageLevel` 'Immediate' | 'Graded/ROP' | 'Modified Level' | 'Standard Level' | 'Preferred Level' | 'null', nullable
  - `draftDay` integer, 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
  - `billingMethod` string, nullable
  - `benefitReminder` string, date, nullable: Benefit reminder date. Canonical format: YYYY-MM-DD
  - `surveyCompleted` boolean, nullable
  - `reasonForPurchase` string, nullable
  - `policyNotes` string, nullable

## Response `200`

PATCH /v2/customers/:id/policies/:policyId Positive response

- PatchV2CustomersIdPoliciesPolicyIdPositiveResponse
  - `id` string, uuid, required
  - `createdAt` string, date-time, nullable, required: Policy creation time. ISO 8601 timestamp
  - `createdBy` string, uuid, nullable, required
  - `updatedAt` string, date-time, nullable, required: Policy last update time. ISO 8601 timestamp
  - `updatedBy` string, uuid, nullable, required
  - `customerId` string, 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
  - `policySubType` string, nullable, required
  - `policyNumber` string, nullable, required
  - `applicationId` string, nullable, required
  - `carrierId` string, uuid, nullable, required
  - `carrierName` string, nullable, required
  - `planName` string, nullable, required
  - `planCode` string, nullable, required
  - `carrierAssignedPolicyId` string, nullable, required
  - `healthSherpaPolicyId` string, nullable, required
  - `sunFireEnrollmentCode` string, nullable, required
  - `connectureConfirmationNumber` string, nullable, required
  - `hiosId` string, 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
  - `applicationApprovalDate` string, date, nullable, required: Application approval date. Canonical format: YYYY-MM-DD
  - `effectiveDate` string, date, nullable, required: Policy effective date. Canonical format: YYYY-MM-DD
  - `terminationDate` string, date, nullable, required: Policy termination date. Canonical format: YYYY-MM-DD
  - `renewalDate` string, date, nullable, required: Policy renewal date. Canonical format: YYYY-MM-DD
  - `enrollmentDate` string, date, nullable, required: Policy enrollment date. Canonical format: YYYY-MM-DD
  - `cancelledDate` string, date, nullable, required: Policy cancellation date. Canonical format: YYYY-MM-DD
  - `declineReason` string, nullable, required
  - `declineReasonDescription` string, nullable, required
  - `cancellationReason` string, nullable, required
  - `cancellationReasonDescription` string, nullable, required
  - `electionPeriod` 'IEP' | 'AEP' | 'OEP' | 'SEP' | 'ICEP' | 'MA-OEP' | 'null', nullable, required
  - `gracePeriodStartDate` string, date, nullable, required: Grace period start date. Canonical format: YYYY-MM-DD
  - `paidThroughDate` string, date, nullable, required: Coverage paid-through date. Canonical format: YYYY-MM-DD
  - `ffmApplicationId` string, nullable, required
  - `ffmSubscriberId` string, nullable, required
  - `aorAgentId` string, uuid, nullable, required
  - `aorFirstName` string, nullable, required
  - `aorLastName` string, nullable, required
  - `aorNpn` string, nullable, required
  - `writingAgentNpn` string, nullable, required
  - `writingAgentName` string, nullable, required
  - `sepType` string, nullable, required
  - `sepCode` string, nullable, required
  - `sepStartDate` string, date, nullable, required: SEP start date. Canonical format: YYYY-MM-DD
  - `sepEndDate` string, date, nullable, required: SEP end date. Canonical format: YYYY-MM-DD
  - `sepDocumentationReceived` boolean, nullable, required
  - `sepDocumentationDate` string, date, nullable, required: SEP documentation date. Canonical format: YYYY-MM-DD
  - `sepNotes` string, nullable, required
  - `monthlyPremium` string, nullable, required
  - `deductible` string, nullable, required
  - `outOfPocketMax` string, nullable, required
  - `subsidyAmount` string, nullable, required
  - `usingSubsidy` boolean, 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
  - `grossPremium` string, nullable, required
  - `netPremium` string, nullable, required
  - `initialCommission` string, nullable, required
  - `renewalCommission` string, nullable, required
  - `spifAmount` string, nullable, required
  - `policyLives` integer, nullable, required
  - `wasAgent` boolean, nullable, required
  - `writtenAs` 'New Business' | 'Like Plan Change' | 'Unlike Plan Change' | 'Reinstatement' | 'Rewrite' | 'null', nullable, required
  - `isReplacing` string, nullable, required
  - `isRewrite` boolean, nullable, required
  - `hospitalNetwork` string, nullable, required
  - `pcpNetwork` string, nullable, required
  - `ssbciVerificationRequired` boolean, nullable, required
  - `dailyBenefit` string, nullable, required
  - `eliminationPeriod` integer, nullable, required
  - `benefitPeriod` integer, nullable, required
  - `hasCola` boolean, nullable, required
  - `deathBenefit` string, nullable, required
  - `term` integer, nullable, required
  - `maturityDate` string, date, nullable, required: Policy maturity date. Canonical format: YYYY-MM-DD
  - `riders` string, nullable, required
  - `coverageLevel` 'Immediate' | 'Graded/ROP' | 'Modified Level' | 'Standard Level' | 'Preferred Level' | 'null', nullable, required
  - `draftDay` integer, nullable, required
  - `exchangeStatus` 'FFM' | 'SBM' | 'SBM FP' | 'OFF EXCHANGE' | 'PRIVATE EXCHANGE' | 'UNKNOWN' | 'null', nullable, required
  - `billingMethod` string, nullable, required
  - `benefitReminder` string, date, nullable, required: Benefit reminder date. Canonical format: YYYY-MM-DD
  - `surveyCompleted` boolean, nullable, required
  - `reasonForPurchase` string, nullable, required
  - `policyNotes` string, nullable, required
  - `customFields` object[]: Structured custom fields with definitions and values. Populated on customer detail and policy detail responses; absent elsewhere.
    - `fieldKey` string: Generated identifier for the field
    - `fieldLabel` string: Display name shown to users
    - `fieldDescription` string: Description of the field's purpose
    - `fieldType` 'text' | 'number' | 'boolean' | 'date' | 'select' | 'multi_select': Type of data this field stores
    - `isRequired` boolean, nullable: Whether this field must have a value
    - `options` string[], nullable: Available options for select/multi-select fields
    - `validationRules` union: Validation rules for the custom field
      - string
      - number
      - boolean
      - object
      - unknown[]
        - unknown
    - `id` string, uuid
    - `fieldDefinitionId` string, uuid: Custom field definition ID
    - `value` union: The actual value for this record (type determined by fieldType). Dates are represented as ISO 8601 strings.
      - string
      - number
      - boolean
      - string[]
      - unknown

## Other responses

- `400`: PATCH /v2/customers/:id/policies/:policyId Negative response 400
- `401`: PATCH /v2/customers/:id/policies/:policyId Negative response 401
- `403`: PATCH /v2/customers/:id/policies/:policyId Negative response 403
- `404`: PATCH /v2/customers/:id/policies/:policyId Negative response 404
- `409`: PATCH /v2/customers/:id/policies/:policyId Negative response 409
- `422`: PATCH /v2/customers/:id/policies/:policyId Negative response 422
- `429`: PATCH /v2/customers/:id/policies/:policyId Negative response 429
- `500`: PATCH /v2/customers/:id/policies/:policyId Negative response 500
- `502`: PATCH /v2/customers/:id/policies/:policyId Negative response 502
- `503`: PATCH /v2/customers/:id/policies/:policyId Negative response 503

---

[API](https://skmtc.dev/carecycle/apis/carecycle-public-api.md) - [All operations](https://skmtc.dev/carecycle/apis/carecycle-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carecycle/apis/carecycle-public-api/revisions/db390c743c36?raw)