---
title: "Sync ACA customers and policies"
method: POST
path: "/v2/sync/aca"
tags: ["Sync", "ACA"]
---

# Sync ACA customers and policies

`POST /v2/sync/aca`

## Request

- Base URL: `https://api.carecycle.ai`
- URL: `https://api.carecycle.ai/v2/sync/aca`
- Auth: API key in header `x-api-key`

Create or update ACA customers and their policies in one request.

**Customer matching** (first identifier present wins): `healthSherpaCustomerId` → `externalId` → `carrierAssignedCustomerId` → fallback on `firstName` + `lastName` + `dateOfBirth` + `phoneNumber`.

**Policy matching**: `healthSherpaPolicyId`, then `carrierAssignedPolicyId`.

**Custom fields**: Put customer values in `records[].customFields` and policy values in `records[].policies[].customFields`. Each entry uses a configured `fieldKey` and `value`. Find keys in [Customer Custom Fields](https://app.carecycle.ai/settings/crm-settings/custom-fields/customer) and [Policy Custom Fields](https://app.carecycle.ai/settings/crm-settings/custom-fields/policy). Policy values are attached to the policy created or matched by the containing policy object.

When a new policy is created, the customer's existing ACA policies with an `effectiveDate` more than one year old are terminated. `policyType` is always set to `ACA`.

**Response**: For each successfully synced record, `results` contains the full customer record (same shape as the `customer.created`/`customer.updated` webhook) along with the policies this request changed: those created or updated from the request, plus any older policies auto-terminated as a side effect. The customer's untouched existing policies are not returned. Each returned policy carries a `previousStatus` field (its status before this request, or `null` if newly created); compare it with the policy's `status` to detect a flip; e.g. an auto-terminated policy comes back with `previousStatus: "Active"` and `status: "Terminated"`.

## Request body

- PostV2SyncAcaRequestBody
  - `records` object[], required: Array of ACA customer/policy records to sync (1-100)
    - `firstName` string, required: Customer first name (required)
    - `lastName` string, required: Customer last name (required)
    - `email` string, nullable
    - `postalCode` union: Customer postal code. Required if timezone is not provided (for TCPA compliance).
      - ''
      - string, nullable: Customer postal code. Required if timezone is not provided (for TCPA compliance).
    - `timezone` union: Customer timezone. Required if postalCode is not provided (for TCPA compliance). Accepts IANA format (America/New_York) or abbreviations (EST, CST, MST, PST).
      - ''
      - string, nullable: Customer timezone. Required if postalCode is not provided (for TCPA compliance). Accepts IANA format (America/New_York) or abbreviations (EST, CST, MST, PST).
    - `state` string, nullable
    - `city` string, nullable
    - `county` string, nullable
    - `address` string, nullable
    - `address2` string, nullable
    - `dateOfBirth` union
      - ''
      - string, nullable: Customer date of birth. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
    - `language` string, nullable
    - `gender` union
      - ''
      - 'Male' | 'Female' | 'Non-Binary' | 'Other' | 'Prefer Not to Say' | 'null', nullable
    - `maritalStatus` union
      - ''
      - 'Single' | 'Married' | 'Divorced' | 'Widowed' | 'Separated' | 'Domestic Partnership' | 'null', nullable
    - `filingStatus` string, nullable
    - `dependentCount` union
      - ''
      - integer, nullable
    - `householdIncome` union
      - ''
      - integer, nullable
    - `isDecisionMaker` union
      - ''
      - boolean, nullable
    - `medicaid` union
      - ''
      - boolean, nullable
    - `medicaidNumber` string, nullable
    - `veteran` union
      - ''
      - boolean, nullable
    - `vaNumber` string, nullable
    - `socialSecurityDisability` union
      - ''
      - boolean, nullable
    - `heightInches` union
      - ''
      - integer, nullable
    - `weightPounds` union
      - ''
      - integer, nullable
    - `smokerStatus` union
      - ''
      - boolean, nullable
    - `carrierAssignedCustomerId` string, nullable: Carrier-assigned customer ID
    - `doNotCall` union
      - ''
      - boolean, nullable
    - `doNotSMS` union
      - ''
      - boolean, nullable
    - `doNotEmail` union
      - ''
      - boolean, nullable
    - `doNotMail` union
      - ''
      - boolean, nullable
    - `healthSherpaCustomerId` string, nullable: Health Sherpa customer ID
    - `phoneNumber` string, required: Customer phone number (required). Accepts: +1XXXXXXXXXX, XXXXXXXXXX, (XXX) XXX-XXXX
    - `externalId` string, nullable: Your external system identifier for this customer
    - `customFields` object[]: Customer custom field values (max 50). Find your configured keys in [Customer Custom Fields](https://app.carecycle.ai/settings/crm-settings/custom-fields/customer).
      - `fieldKey` string, required: Custom field key (e.g., 'lead_source', 'utm_campaign')
      - `value` union, required: Value for the custom field
        - string
        - number
        - boolean
        - string[]
    - `policies` object[]: ACA policies to sync (max 10). policyType is set automatically to 'ACA'.
      - `planName` string, nullable, required: Name of the policy
      - `planCode` string, nullable, required: Plan code of the policy
      - `carrierName` string, nullable, required: 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.
      - `policyNumber` string, nullable
      - `policySubType` string, nullable
      - `applicationId` string, nullable
      - `carrierAssignedPolicyId` string, nullable: Carrier-assigned policy ID (secondary identifier for matching)
      - `status` union
        - ''
        - 'Active' | 'Placed' | 'Pending' | 'Pending Effectuation' | 'Pending Followup' | 'Suspended' | 'Cancelled' | 'Terminated' | 'Future Cancel' | 'Deceased' | 'Not Approved' | 'null', nullable: The current status of the policy
      - `applicationApprovalDate` union
        - ''
        - string, nullable: Application approval date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `effectiveDate` string, nullable, required: Policy effective date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `terminationDate` union
        - ''
        - string, nullable: Policy termination date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `renewalDate` union
        - ''
        - string, nullable: Policy renewal date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `enrollmentDate` string, nullable, required: Enrollment date (application submitted). Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `cancelledDate` union
        - ''
        - string, nullable: Policy cancelled date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `electionPeriod` union
        - ''
        - 'IEP' | 'AEP' | 'OEP' | 'SEP' | 'ICEP' | 'MA-OEP' | 'null', nullable
      - `aorFirstName` string, nullable: Agent Of Record First Name
      - `aorLastName` string, nullable: Agent Of Record Last Name
      - `aorNpn` string, nullable, required: Agent Of Record NPN
      - `writingAgentNpn` string, nullable, required
      - `writingAgentName` string, nullable
      - `sepType` string, nullable
      - `sepCode` string, nullable
      - `sepStartDate` union
        - ''
        - string, nullable: SEP start date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `sepEndDate` union
        - ''
        - string, nullable: SEP end date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `sepDocumentationReceived` union
        - ''
        - boolean, nullable
      - `sepDocumentationDate` union
        - ''
        - string, nullable: SEP documentation date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `sepNotes` string, nullable
      - `monthlyPremium` string, nullable
      - `deductible` string, nullable
      - `outOfPocketMax` string, nullable
      - `initialCommission` string, nullable
      - `renewalCommission` string, nullable
      - `spifAmount` string, nullable
      - `policyLives` union
        - ''
        - integer, nullable: Number of lives covered by the policy
      - `wasAgent` union
        - ''
        - boolean, nullable
      - `writtenAs` union
        - ''
        - 'New Business' | 'Like Plan Change' | 'Unlike Plan Change' | 'Reinstatement' | 'Rewrite' | 'null', nullable
      - `isReplacing` string, nullable
      - `isRewrite` union
        - ''
        - boolean, nullable
      - `reasonForPurchase` string, nullable
      - `policyNotes` string, nullable
      - `healthSherpaPolicyId` string, nullable: Health Sherpa policy ID (primary identifier for matching)
      - `hiosId` string, nullable
      - `metalLevel` union
        - ''
        - 'Catastrophic' | 'Bronze' | 'Expanded Bronze' | 'Silver' | 'Gold' | 'Platinum' | 'null', nullable
      - `gracePeriodStartDate` union
        - ''
        - string, nullable: Grace period start date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `paidThroughDate` union
        - ''
        - string, nullable: Coverage paid through date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - `ffmApplicationId` string, nullable
      - `ffmSubscriberId` string, nullable
      - `subsidyAmount` string, nullable
      - `usingSubsidy` union
        - ''
        - boolean, nullable
      - `premiumMode` union
        - ''
        - 'Monthly' | 'Quarterly' | 'Semi-Annual' | 'Annual' | 'null', nullable
      - `paymentMode` union
        - ''
        - 'ACH' | 'Credit/ debit card' | 'Direct bill' | 'null', nullable
      - `paymentMethod` union
        - ''
        - 'Credit Card' | 'Debit Card' | 'Check' | 'ACH / Bank Draft' | 'Money Order' | 'Cash' | 'Other' | 'null', nullable
      - `grossPremium` string, nullable
      - `netPremium` string, nullable
      - `exchangeStatus` union
        - ''
        - 'FFM' | 'SBM' | 'SBM FP' | 'OFF EXCHANGE' | 'PRIVATE EXCHANGE' | 'UNKNOWN' | 'null', nullable
      - `customFields` object[]: Policy custom field values (max 50). Find your configured keys in [Policy Custom Fields](https://app.carecycle.ai/settings/crm-settings/custom-fields/policy). Values are written to the policy created or matched by this policy object.
        - `fieldKey` string, required: Custom field key (e.g., 'lead_source', 'utm_campaign')
        - `value` union, required: Value for the custom field
          - string
          - number
          - boolean
          - string[]

## Response `200`

POST /v2/sync/aca Positive response

- PostV2SyncAcaPositiveResponse
  - `succeeded` number, required: Number of successfully synced records
  - `failed` number, required: Number of failed records
  - `results` object[], required: The full customer record for each successfully synced row, each with the policies that this request changed
    - `id` string, required
    - `createdAt` string, date-time, nullable, required: Customer creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, nullable, required: Customer last update time. ISO 8601 timestamp
    - `deletedAt` string, date-time, nullable, required: Customer deletion time. ISO 8601 timestamp
    - `externalId` string, nullable, required
    - `status` string, nullable, required
    - `firstName` string, nullable, required
    - `middleName` string, nullable, required
    - `lastName` string, nullable, required
    - `salutation` string, nullable, required
    - `suffix` string, nullable, required
    - `preferredName` string, nullable, required
    - `phoneNumber` string, required
    - `isPhonePrimary` boolean, required
    - `lineType` string, nullable, required
    - `email` string, nullable, required
    - `dateOfBirth` string, date, nullable, required: Customer date of birth. Canonical format: YYYY-MM-DD
    - `language` string, nullable, required
    - `ethnicity` string, nullable, required
    - `gender` string, nullable, required
    - `maritalStatus` string, nullable, required
    - `address` string, nullable, required
    - `address2` string, nullable, required
    - `city` string, nullable, required
    - `county` string, nullable, required
    - `state` string, nullable, required
    - `postalCode` string, nullable, required
    - `timezone` string, nullable, required
    - `mbiNumber` string, nullable, required
    - `medicareCard` boolean, nullable, required
    - `medicarePartADate` string, date, nullable, required: Medicare Part A effective date. Canonical format: YYYY-MM-DD
    - `medicarePartBDate` string, date, nullable, required: Medicare Part B effective date. Canonical format: YYYY-MM-DD
    - `hasMedicaid` boolean, nullable, required
    - `medicaidNumber` string, nullable, required
    - `socialSecurityDisability` boolean, nullable, required
    - `heightInches` number, nullable, required
    - `weightPounds` number, nullable, required
    - `smokerStatus` boolean, nullable, required
    - `veteran` boolean, nullable, required
    - `vaNumber` string, nullable, required
    - `householdIncome` number, nullable, required
    - `annualIncome` number, nullable, required
    - `filingStatus` string, nullable, required
    - `dependentCount` number, nullable, required
    - `subsidyEligible` boolean, nullable, required
    - `subsidyAmount` number, nullable, required
    - `carrierAssignedCustomerId` string, nullable, required
    - `agentName` string, nullable, required
    - `agentNpn` number, nullable, required
    - `assignedUser` object, nullable, required
      - `id` string, required
      - `name` string, required
      - `email` string, required
      - `npn` string, nullable, required
      - `role` string, required
      - `licensedStates` string[], nullable, required
    - `doNotCall` boolean, nullable, required
    - `doNotSMS` boolean, nullable, required
    - `doNotEmail` boolean, nullable, required
    - `doNotMail` boolean, nullable, required
    - `testCustomer` boolean, required
    - `policies` object[], required: Policies changed by this request: those created or updated from the request, plus any older policies auto-terminated as a side effect. Does NOT include the customer's untouched existing policies.
      - `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[], required: Policy custom fields after this sync, including definition metadata and the stored value.
        - `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
      - `previousStatus` string, nullable, required
  - `errors` object[], required: Errors for failed records (empty if all succeeded)
    - `id` string, uuid, nullable, required
    - `externalId` string, nullable, required
    - `error` string, required: Error message

## Other responses

- `400`: POST /v2/sync/aca Negative response 400
- `401`: POST /v2/sync/aca Negative response 401
- `403`: POST /v2/sync/aca Negative response 403
- `404`: POST /v2/sync/aca Negative response 404
- `409`: POST /v2/sync/aca Negative response 409
- `422`: POST /v2/sync/aca Negative response 422
- `429`: POST /v2/sync/aca Negative response 429
- `500`: POST /v2/sync/aca Negative response 500
- `502`: POST /v2/sync/aca Negative response 502
- `503`: POST /v2/sync/aca 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)