Get paginated list of customers
List your customers. You can filter and search, and results come back one page at a time.
Authorization
x-api-key API key required for authentication.
Keys begin with 'cc_' prefix. Get your API key from the Developer Dashboard.
In: header
Query Parameters
GET /v2/customers Parameter
GET /v2/customers Parameter
Field to sort by
Sort direction
GET /v2/customers Parameter
Search query for filtering customers by customer ID, client customer ID, name, phone, email, ZIP code, MBI, or policy enrollment code.
Comma-separated list of columns whose displayed text the search also matches: location, source, tags, campaigns, planName, carrierName, policyStatus, or customField:<key> for a text, select, or multi-select custom field. Location matches a full state name; the others need a search of 3+ characters. Unknown entries are ignored.
Include test phone numbers in results
Filter customers by source IDs (comma-separated)
Filter customers by known tag IDs (comma-separated, OR logic)
Filter customers by campaign IDs (comma-separated, OR logic)
How campaignIds is matched. 'include' (default): customers enrolled in any of the campaigns, in any status. 'exclude': customers who have NEVER been enrolled in any of the campaigns (no customerCampaign row for them, in any status) - use to target the book that has not yet touched a campaign.
Filter customers by customerCampaign status (comma-separated, OR logic - matches if customer has any of these statuses in any campaign)
Filter campaign customers by whether they have prior attempts
Filter customers by their customerCampaign canonical failure reason code (comma-separated, OR logic). Use with campaignIds to drill into a single campaign's exit reason.
Filter customers by their current Pulse node ID
Filter customers by policy status (comma-separated, OR logic). Valid values: Active, Placed, Pending, Pending Effectuation, Pending Followup, Suspended, Cancelled, Terminated, Future Cancel, Deceased, Not Approved
Exclude customers with active coverage, or with active/pending coverage
Filter customers by assigned member IDs (comma-separated, OR logic). Use 'unassigned' to filter customers with no assignee.
Filter customers by customer status (comma-separated, OR logic). Valid values: Lead, Active, Inactive
Which date the startDate/endDate range filters on: customer creation, or a policy date. Policy-derived conditions in the request must all match the same policy.
Inclusive start bound per dateField: YYYY-MM-DD at UTC midnight or an exact ISO timestamp. Policy DATE values represent UTC midnight.
End bound per dateField. YYYY-MM-DD includes that UTC calendar day; a full ISO timestamp is exact and exclusive.
Inclusive call start bound: YYYY-MM-DD at UTC midnight or an exact ISO timestamp.
Call end bound. YYYY-MM-DD includes that UTC calendar day; a full ISO timestamp is exact and exclusive.
Filter customers by the disposition of their most recent call (comma-separated, OR logic). Calls with system error dispositions are ignored, matching the list's Last Contact column.
List filters to invert, comma-separated (campaignStatuses, lastCallDispositions). campaignStatuses: customers with NO enrollment in those statuses (scoped to campaignIds in include mode, so campaignIds=X&campaignStatuses=completed&negatedFilters=campaignStatuses is "in campaign X and not completed there"). lastCallDispositions: customers whose last call has none of them, including customers never called.
Contact permission conditions, comma-separated and ANDed (can_call, do_not_call, can_text, do_not_text). A suppressed customer counts as both do_not_call and do_not_text, matching the list's icons.
Compare the customer's call count, counted like the list's Total Calls column: operator:count (eq, neq, gt, gte, lt, lte), or between:min:max (inclusive). Example: gte:2.
Filter customers by US state (comma-separated, OR logic)
Filter customers by county (comma-separated, OR logic)
Filter customers who have a policy of any of these types (comma-separated, OR logic). Valid values: 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
Filter customers whose 65th birthday falls within the next 3/6/12 months (Medicare aging-in)
Comparison for the policy subsidy amount filter. Requires subsidyValue (and subsidyValueTo when 'between').
Subsidy amount to compare against (dollars). For 'between', this is the lower bound.
Upper bound for the 'between' subsidy comparison.
Filter customers by custom field values (ANDed). JSON array of { key, operator, value? }. Operators: eq, neq, gt, gte, lt, lte, is_empty, is_not_empty.
When set, sort by this custom field's value (key from GET /v2/custom-fields) using sortDirection, overriding sortBy.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.carecycle.ai/v2/customers"{
"itemsTotal": 0,
"currentPage": 0,
"nextPage": 0,
"prevPage": 0,
"items": [
{
"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",
"clientId": "5e505642-9024-474d-9434-e5a44f505cc5",
"clientCustomerId": "string",
"status": "Lead",
"qualificationStatus": "Qualified",
"intent": "High",
"isDecisionMaker": true,
"disqualificationReason": "string",
"productInterest": "string",
"productFamily": "string",
"salutation": "string",
"suffix": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"preferredName": "string",
"callerId": "string",
"isPhonePrimary": true,
"lineType": "landline",
"email": "string",
"dateOfBirth": "2019-08-24",
"language": "string",
"ethnicity": "string",
"gender": "Male",
"maritalStatus": "Single",
"heightInches": -2147483648,
"weightPounds": -2147483648,
"smokerStatus": true,
"postalCode": "string",
"timezone": "string",
"state": "string",
"city": "string",
"county": "string",
"countyFips": "strin",
"address": "string",
"address2": "string",
"mbiNumber": "string",
"medicareCard": true,
"medicarePartADate": "2019-08-24",
"medicarePartBDate": "2019-08-24",
"medicaid": true,
"medicaidNumber": "string",
"socialSecurityDisability": true,
"veteran": true,
"vaNumber": "string",
"healthSherpaCustomerId": "string",
"householdIncome": -2147483648,
"annualIncome": -2147483648,
"filingStatus": "string",
"dependentCount": -2147483648,
"subsidyAmount": -2147483648,
"subsidyEligible": true,
"existingCoverage": "None",
"existingCoveragePlanName": "string",
"existingCoverageCarrier": "string",
"desiredCoverageStartDate": "2019-08-24",
"currentSourceId": "92ff85a4-bd9b-47e4-9ade-cbb65530f3f4",
"originalSourceId": "a3edc39e-7854-4380-8541-1f199004a6a0",
"agentName": "string",
"agentNpn": -2147483648,
"memberId": "92983ab9-49c8-444b-85ae-6e40402cf72e",
"carrierName": "string",
"planName": "string",
"planCode": "string",
"enrollmentDate": "2019-08-24",
"effectiveDate": "2019-08-24",
"carrierAssignedCustomerId": "string",
"suppressed": true,
"doNotCall": true,
"doNotSMS": true,
"doNotEmail": true,
"doNotMail": true,
"lastContactedAt": "2019-08-24T14:15:22Z",
"convertedAt": "2019-08-24T14:15:22Z",
"testCustomer": true,
"ssnLast4": "string",
"mutationScope": {
"canEdit": true,
"canReassign": true,
"canDelete": true,
"canEditTags": true
},
"carrierSmsConsent": {
"blocked": true,
"recordedAt": "2019-08-24T14:15:22Z",
"source": "string",
"matchedKeyword": "string"
},
"phoneNumberCustomerCount": 0,
"phonePrimaryCustomerId": "e94124a8-9a97-4607-865c-f6a31d48e6a9",
"totalCalls": 0,
"lastCallDate": "2019-08-24T14:15:22Z",
"lastCallDisposition": "string",
"campaigns": [],
"source": {
"id": "string",
"name": "string",
"sourceId": "string"
},
"customFields": [],
"policies": [],
"planCrosswalk": {
"cohort": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"fromYear": -9007199254740991,
"toYear": -9007199254740991,
"completedAt": "2019-08-24T14:15:22Z",
"governmentCrosswalkLoaded": true
},
"items": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
"fromPlanId": "string",
"toPlanId": "string",
"outcome": "renewed",
"primaryBucket": "plan_terminated",
"impacts": [
"plan_terminated"
],
"skipReason": "no_plan_code",
"planCodeOnFile": "string",
"fromPlanName": "string",
"carrier": "string",
"toPlanName": "string",
"county": "string",
"changeSummary": "string",
"changes": {
"monthlyPremium": {
"from": 0,
"to": 0
},
"maxOutOfPocket": {
"from": 0,
"to": 0
},
"healthDeductible": {
"from": 0,
"to": 0
},
"drugDeductible": {
"from": 0,
"to": 0
},
"starRating": {
"from": 0,
"to": 0
},
"benefitsLost": [
"string"
],
"benefitsGained": [
"string"
],
"successorPlanIds": [
"string"
]
},
"recommendations": [
{
"planId": "string",
"planName": "string",
"differences": [
"string"
]
}
]
}
]
},
"displayPolicyId": "a450b56f-b3dd-431c-a60a-9d32cc1c80f4",
"prescriptions": [],
"providers": [],
"scopeOfAppointments": [],
"dependents": [],
"assignedMember": {
"id": "string",
"name": "string",
"email": "string",
"image": "string"
},
"tags": []
}
]
}{
"message": "string",
"code": "string",
"details": {
"property1": null,
"property2": null
}
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string",
"details": {
"property1": null,
"property2": null
}
}{
"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"
}