Sync ACA customers and policies
Syncs ACA customers and policies.
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 and Policy Custom Fields. 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".
Authorization
x-api-key API key required for authentication.
Keys begin with 'cc_' prefix. Get your API key from the Developer Dashboard.
In: header
Request Body
application/json
POST /v2/sync/aca Request body
TypeScript Definitions
Use the request body type in TypeScript.
Array of ACA customer/policy records to sync (1-100)
Customer first name (required)
Customer last name (required)
Customer phone number (required). Accepts: +1XXXXXXXXXX, XXXXXXXXXX, (XXX) XXX-XXXX
Customer postal code. Required if timezone is not provided (for TCPA compliance).
Customer timezone. Required if postalCode is not provided (for TCPA compliance). Accepts IANA format (America/New_York) or abbreviations (EST, CST, MST, PST).
Carrier-assigned customer ID
Health Sherpa customer ID
Your external system identifier for this customer
Customer custom field values (max 50). Find your configured keys in Customer Custom Fields.
Custom field key (e.g., 'lead_source', 'utm_campaign')
Value for the custom field
ACA policies to sync (max 10). policyType is set automatically to 'ACA'.
Name of the policy
Plan code of the policy
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.
Policy effective date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
Enrollment date (application submitted). Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
Agent Of Record NPN
Carrier-assigned policy ID (secondary identifier for matching)
Agent Of Record First Name
Agent Of Record Last Name
Health Sherpa policy ID (primary identifier for matching)
Policy custom field values (max 50). Find your configured keys in Policy Custom Fields. Values are written to the policy created or matched by this policy object.
Custom field key (e.g., 'lead_source', 'utm_campaign')
Value for the custom field
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.carecycle.ai/v2/sync/aca" \ -H "Content-Type: application/json" \ -d '{ "records": [ { "firstName": "string", "lastName": "string", "phoneNumber": "string" } ] }'{
"succeeded": 0,
"failed": 0,
"results": [
{
"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": "2019-08-24T14:15:22Z",
"externalId": "string",
"status": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"salutation": "string",
"suffix": "string",
"preferredName": "string",
"phoneNumber": "string",
"lineType": "string",
"email": "string",
"dateOfBirth": "2019-08-24",
"language": "string",
"ethnicity": "string",
"gender": "string",
"maritalStatus": "string",
"address": "string",
"address2": "string",
"city": "string",
"county": "string",
"state": "string",
"postalCode": "string",
"timezone": "string",
"mbiNumber": "string",
"medicareCard": true,
"medicarePartADate": "2019-08-24",
"medicarePartBDate": "2019-08-24",
"hasMedicaid": true,
"medicaidNumber": "string",
"socialSecurityDisability": true,
"heightInches": 0,
"weightPounds": 0,
"smokerStatus": true,
"veteran": true,
"vaNumber": "string",
"householdIncome": 0,
"annualIncome": 0,
"filingStatus": "string",
"dependentCount": 0,
"subsidyEligible": true,
"subsidyAmount": 0,
"carrierAssignedCustomerId": "string",
"agentName": "string",
"agentNpn": 0,
"assignedUser": {
"id": "string",
"name": "string",
"email": "string",
"npn": "string",
"role": "string",
"licensedStates": [
"string"
]
},
"doNotCall": true,
"doNotSMS": true,
"doNotEmail": true,
"doNotMail": true,
"testCustomer": true,
"policies": [
{
"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",
"coverageLevel": "Immediate",
"draftDay": -2147483648,
"exchangeStatus": "FFM",
"billingMethod": "string",
"benefitReminder": "2019-08-24",
"surveyCompleted": true,
"reasonForPurchase": "string",
"policyNotes": "string",
"customFields": [
{
"fieldKey": "string",
"fieldLabel": "string",
"fieldDescription": "string",
"fieldType": "text",
"isRequired": true,
"options": [
"string"
],
"validationRules": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"fieldDefinitionId": "079f459a-0b19-4274-98b0-427a624178ff",
"value": "string"
}
],
"previousStatus": "string"
}
]
}
],
"errors": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"externalId": "string",
"error": "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"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}