---
title: "Get customer by ID"
method: GET
path: "/v2/customers/{id}"
tags: ["Customers"]
---

# Get customer by ID

`GET /v2/customers/{id}`

## Request

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

Look up one customer and everything on their record. This includes policies, prescriptions, providers, Scope of Appointment forms (SOAs), dependents, and custom fields.

## Path parameters

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

## Response `200`

GET /v2/customers/:id Positive response

- GetV2CustomersIdPositiveResponse: Customer
  - `id` string, uuid, required
  - `createdAt` string, date-time, nullable, required: Customer creation time. ISO 8601 timestamp
  - `createdBy` string, uuid, nullable, required
  - `updatedAt` string, date-time, nullable, required: Customer last update time. ISO 8601 timestamp
  - `updatedBy` string, uuid, nullable, required
  - `clientId` string, uuid, required
  - `clientCustomerId` string, nullable, required
  - `status` 'Lead' | 'Active' | 'Inactive' | 'null', nullable, required
  - `qualificationStatus` 'Qualified' | 'Disqualified' | 'Pending Review' | 'Needs Information' | 'In Progress' | 'null', nullable, required
  - `intent` 'High' | 'Medium' | 'Low' | 'Unknown' | 'null', nullable, required
  - `isDecisionMaker` boolean, nullable, required
  - `disqualificationReason` string, nullable, required
  - `productInterest` string, nullable, required
  - `productFamily` string, nullable, required
  - `salutation` string, nullable, required
  - `suffix` string, nullable, required
  - `firstName` string, nullable, required
  - `middleName` string, nullable, required
  - `lastName` string, nullable, required
  - `preferredName` string, nullable, required
  - `callerId` string, required
  - `isPhonePrimary` boolean, required
  - `lineType` 'landline' | 'mobile' | 'fixedVoip' | 'nonFixedVoip' | 'personal' | 'tollFree' | 'premium' | 'sharedCost' | 'uan' | 'voicemail' | 'pager' | 'unknown' | 'null', 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` 'Male' | 'Female' | 'Non-Binary' | 'Other' | 'Prefer Not to Say' | 'null', nullable, required
  - `maritalStatus` 'Single' | 'Married' | 'Divorced' | 'Widowed' | 'Separated' | 'Domestic Partnership' | 'null', nullable, required
  - `heightInches` integer, nullable, required
  - `weightPounds` integer, nullable, required
  - `smokerStatus` boolean, nullable, required
  - `postalCode` string, nullable, required
  - `timezone` string, nullable, required
  - `state` string, nullable, required
  - `city` string, nullable, required
  - `county` string, nullable, required
  - `countyFips` string, nullable, required
  - `address` string, nullable, required
  - `address2` 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
  - `medicaid` boolean, nullable, required
  - `medicaidNumber` string, nullable, required
  - `socialSecurityDisability` boolean, nullable, required
  - `veteran` boolean, nullable, required
  - `vaNumber` string, nullable, required
  - `healthSherpaCustomerId` string, nullable, required
  - `householdIncome` integer, nullable, required
  - `annualIncome` integer, nullable, required
  - `filingStatus` string, nullable, required
  - `dependentCount` integer, nullable, required
  - `subsidyAmount` integer, nullable, required
  - `subsidyEligible` boolean, nullable, required
  - `existingCoverage` 'None' | 'Medicare Advantage' | 'Original Medicare' | 'Medicaid' | 'Employer' | 'Marketplace/ACA' | 'Other' | 'null', nullable, required
  - `existingCoveragePlanName` string, nullable, required
  - `existingCoverageCarrier` string, nullable, required
  - `desiredCoverageStartDate` string, date, nullable, required: Desired coverage start date. Canonical format: YYYY-MM-DD
  - `currentSourceId` string, uuid, nullable, required
  - `originalSourceId` string, uuid, nullable, required
  - `agentName` string, nullable, required
  - `agentNpn` integer, nullable, required
  - `memberId` string, uuid, nullable, required
  - `carrierName` string, nullable, required
  - `planName` string, nullable, required
  - `planCode` string, nullable, required
  - `enrollmentDate` string, date, nullable, required: Customer enrollment date. Canonical format: YYYY-MM-DD
  - `effectiveDate` string, date, nullable, required: Customer coverage effective date. Canonical format: YYYY-MM-DD
  - `carrierAssignedCustomerId` string, nullable, required
  - `suppressed` boolean, required
  - `doNotCall` boolean, nullable, required
  - `doNotSMS` boolean, nullable, required
  - `doNotEmail` boolean, nullable, required
  - `doNotMail` boolean, nullable, required
  - `lastContactedAt` string, date-time, nullable, required: Customer last contact time. ISO 8601 timestamp
  - `convertedAt` string, date-time, nullable, required: Customer conversion time. ISO 8601 timestamp
  - `testCustomer` boolean, required
  - `ssnLast4` string, nullable, required
  - `carrierSmsConsent` object
    - `blocked` boolean, required
    - `recordedAt` string, date-time, nullable, required: Carrier SMS consent record time. ISO 8601 timestamp
    - `source` string, nullable, required
    - `matchedKeyword` string, nullable, required
  - `phoneNumberCustomerCount` number: Customers on this phone number, this one included. Call and SMS opt-outs apply to all of them.
  - `phonePrimaryCustomerId` string, uuid, nullable: The primary customer on this phone number. Texts with the number live on their conversation.
  - `totalCalls` number: Total number of calls made to this customer
  - `lastCallDate` string, date-time, nullable: Most recent call time. ISO 8601 timestamp
  - `lastCallDisposition` string, nullable: Disposition of the most recent call
  - `campaigns` object[], required: Campaigns this customer is enrolled in
    - `customerCampaignId` string, required
    - `campaignId` string, required
    - `campaignName` string, required
    - `campaignStatus` string, required
    - `campaignLifecycleStatus` string, required
    - `campaignIsReceptionist` boolean, required
    - `isActive` boolean, required
    - `attempts` number
    - `pulseNodeId` string, nullable
    - `pulseNodeType` string, nullable
    - `pulseStatus` string, nullable
    - `pulseLastTransitionAt` string, date-time, nullable: Campaign workflow last transition time. ISO 8601 timestamp
    - `pulseWaitNodeId` string, nullable: Wait step the customer entered on their latest Pulse transition (Live View counts them there; pulseNodeId is the step that runs after it). Detail endpoint only.
    - `statusReason` object, nullable: Client-safe explanation of why the customer was failed/skipped
      - `code` string, required
      - `category` string, required
      - `label` string, required
      - `description` string, required
  - `source` object, nullable: Source information for this customer
    - `id` string, required
    - `name` string, required
    - `sourceId` string, required
  - `customFields` object[], required: Structured custom fields with definitions and values
    - `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
  - `policies` object[], required: List of policies associated with the customer
    - `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
  - `planCrosswalk` object, nullable: Latest completed plan crosswalk containing this customer
    - `cohort` object, required
      - `id` string, uuid, required
      - `name` string, required
      - `fromYear` integer, required
      - `toYear` integer, required
      - `completedAt` string, date-time, nullable, required
      - `governmentCrosswalkLoaded` boolean, required
    - `items` object[], required
      - `id` string, uuid, required
      - `customerId` string, uuid, required
      - `fromPlanId` string, nullable, required
      - `toPlanId` string, nullable, required
      - `outcome` 'renewed' | 'consolidated' | 'split' | 'service_area_reduction' | 'terminated' | 'not_found' | 'skipped', required
      - `primaryBucket` 'plan_terminated' | 'service_area_reduction' | 'plan_not_found' | 'plan_split' | 'plan_consolidated' | 'benefit_loss' | 'premium_increase' | 'moop_increase' | 'deductible_increase' | 'star_rating_decrease' | 'no_material_change' | 'null', nullable, required
      - `impacts` string[], required
      - `skipReason` 'no_plan_code' | 'unparseable_plan_code' | 'plan_not_found' | 'county_unresolved' | 'county_outside_plan_area' | 'plan_name_unmatched' | 'plan_name_ambiguous' | 'null', nullable, required
      - `planCodeOnFile` string, nullable, required
      - `fromPlanName` string, nullable, required
      - `carrier` string, nullable, required
      - `toPlanName` string, nullable, required
      - `county` string, nullable, required
      - `changeSummary` string, nullable, required
      - `changes` object, nullable, required
        - `monthlyPremium` object, required
          - `from` number, nullable, required
          - `to` number, nullable, required
        - `maxOutOfPocket` object, required
          - `from` number, nullable, required
          - `to` number, nullable, required
        - `healthDeductible` object, required
          - `from` number, nullable, required
          - `to` number, nullable, required
        - `drugDeductible` object, required
          - `from` number, nullable, required
          - `to` number, nullable, required
        - `starRating` object, required
          - `from` number, nullable, required
          - `to` number, nullable, required
        - `benefitsLost` string[], required
        - `benefitsGained` string[], required
        - `successorPlanIds` string[], required
      - `recommendations` object[], required
        - `planId` string, required
        - `planName` string, nullable, required
        - `differences` string[], required
  - `displayPolicyId` string, uuid, nullable, required
  - `prescriptions` object[], required: List of prescription names associated with the customer
    - `id` string, uuid, required
    - `createdAt` string, date-time, nullable, required: Prescription creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, nullable, required: Prescription last update time. ISO 8601 timestamp
    - `customerId` string, uuid, required
    - `name` string, nullable, required
    - `dosage` string, nullable, required
    - `frequency` string, nullable, required
    - `route` 'Oral' | 'Topical' | 'Injection' | 'Inhalation' | 'Sublingual' | 'Rectal' | 'Intravenous' | 'null', nullable, required
    - `status` 'Active' | 'Expired' | 'Discontinued' | 'null', nullable, required
    - `connectureDrugId` string, nullable, required
    - `connectureDosageId` string, nullable, required
    - `connecturePackageId` string, nullable, required
    - `ndc` string, nullable, required
    - `dosageName` string, nullable, required
    - `drugTypeId` integer, nullable, required
    - `userQuantity` number, nullable, required
    - `metricQuantity` number, nullable, required
    - `daysSupply` integer, nullable, required
    - `packageDescription` string, nullable, required
    - `packageSize` number, nullable, required
    - `packageQuantity` number, nullable, required
  - `providers` object[], required: List of providers associated with the customer
    - `id` string, uuid, required
    - `createdAt` string, date-time, nullable, required: Provider creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, nullable, required: Provider last update time. ISO 8601 timestamp
    - `customerId` string, uuid, required
    - `providerType` 'Primary Care' | 'Specialist' | 'Hospital' | 'Pharmacy', required
    - `specialty` string, nullable, required
    - `providerName` string, nullable, required
    - `practiceName` string, nullable, required
    - `npi` string, nullable, required
    - `phone` string, nullable, required
    - `fax` string, nullable, required
    - `email` string, nullable, required
    - `address` string, nullable, required
    - `address2` string, nullable, required
    - `city` string, nullable, required
    - `state` string, nullable, required
    - `postalCode` string, nullable, required
    - `isPrimaryProvider` boolean, nullable, required
    - `isActive` boolean, nullable, required
    - `notes` string, nullable, required
    - `connectureProviderId` string, nullable, required
    - `connectureAddressId` string, nullable, required
    - `isIndividual` boolean, nullable, required
  - `scopeOfAppointments` object[], required: List of scope of appointments associated with the customer
    - `id` string, uuid, required
    - `createdAt` string, date-time, nullable, required: Scope of appointment creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, nullable, required: Scope of appointment last update time. ISO 8601 timestamp
    - `customerId` string, uuid, required
    - `productsDiscussed` string, nullable, required
    - `planTypes` string, nullable, required
    - `agentName` string, nullable, required
    - `agentNpn` string, nullable, required
    - `consentGiven` boolean, nullable, required
    - `consentDate` string, date-time, nullable, required: Scope of appointment consent time. ISO 8601 timestamp
    - `status` 'Pending' | 'Completed' | 'Expired' | 'Cancelled' | 'null', nullable, required
    - `expirationDate` string, date, nullable, required: Scope of appointment expiration date. Canonical format: YYYY-MM-DD
    - `isValid` boolean, nullable, required
    - `documentUrl` string, nullable, required
    - `notes` string, nullable, required
  - `dependents` object[], required: List of dependents associated with the customer
    - `id` string, uuid, required
    - `createdAt` string, date-time, nullable, required: Dependent creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, nullable, required: Dependent last update time. ISO 8601 timestamp
    - `customerId` string, uuid, required
    - `firstName` string, nullable, required
    - `lastName` string, nullable, required
    - `middleName` string, nullable, required
    - `dateOfBirth` string, date, nullable, required: Dependent date of birth. Canonical format: YYYY-MM-DD
    - `gender` 'Male' | 'Female' | 'Non-Binary' | 'Other' | 'Prefer Not to Say' | 'null', nullable, required
    - `annualIncome` integer, nullable, required
    - `relationshipType` 'Spouse' | 'Child' | 'Parent' | 'Sibling' | 'Other' | 'null', nullable, required
    - `phone` string, nullable, required
    - `email` string, nullable, required
    - `isCovered` boolean, nullable, required
    - `coverageStartDate` string, date, nullable, required: Dependent coverage start date. Canonical format: YYYY-MM-DD
    - `coverageEndDate` string, date, nullable, required: Dependent coverage end date. Canonical format: YYYY-MM-DD
    - `isActive` boolean, nullable, required
    - `notes` string, nullable, required
  - `assignedMember` object, nullable: The team member assigned to this customer
    - `id` string, required
    - `name` string, nullable, required
    - `email` string, required
    - `image` string, nullable, required
  - `tags` object[], required: Tags assigned to this customer
    - `id` string, uuid, required
    - `name` string, required
    - `color` string, nullable: Color picked for the tag; null means automatic

## Other responses

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