---
title: "Add related customer"
method: POST
path: "/v2/customers/{id}/related"
tags: ["Customers.Relationships"]
---

# Add related customer

`POST /v2/customers/{id}/related`

## Request

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

Add a person who shares this customer's phone number, such as a spouse, or link an existing customer. Call it when POST /v2/customers returns 409 with an existingCustomerId. A person already on the number is returned instead of duplicated, so retries are safe. The person is not the number's primary unless isPrimaryForPhone is true.

## Path parameters

- `id` string, uuid, required: Customer the person is related to

## Request body

- PostV2CustomersIdRelatedRequestBody
  - `relationshipType` 'spouse' | 'child' | 'parent' | 'sibling' | 'power_of_attorney' | 'other', required: What the related customer is to the customer in the path, for example spouse or child
  - `relatedCustomerId` string, uuid: Link an existing customer instead of adding a person
  - `person` object: A person who shares this customer's phone number. They get the number, its call and text opt-outs, and the customer's assigned agent. Send mbiNumber, clientCustomerId (your own ID for the person), or firstName, lastName and dateOfBirth so repeat requests match them; at least one is required.
    - `clientCustomerId` string, nullable
    - `status` 'Lead' | 'Active' | 'Inactive' | 'null', nullable
    - `qualificationStatus` 'Qualified' | 'Disqualified' | 'Pending Review' | 'Needs Information' | 'In Progress' | 'null', nullable
    - `intent` 'High' | 'Medium' | 'Low' | 'Unknown' | 'null', nullable
    - `isDecisionMaker` boolean, nullable
    - `disqualificationReason` string, nullable
    - `productInterest` string, nullable
    - `productFamily` string, nullable
    - `salutation` string, nullable
    - `suffix` string, nullable
    - `firstName` string, nullable
    - `middleName` string, nullable
    - `lastName` string, nullable
    - `preferredName` string, nullable
    - `lineType` 'landline' | 'mobile' | 'fixedVoip' | 'nonFixedVoip' | 'personal' | 'tollFree' | 'premium' | 'sharedCost' | 'uan' | 'voicemail' | 'pager' | 'unknown' | 'null', nullable
    - `email` string, nullable
    - `dateOfBirth` union
      - string: Customer date of birth. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - ''
    - `language` string, nullable
    - `ethnicity` string, nullable
    - `gender` 'Male' | 'Female' | 'Non-Binary' | 'Other' | 'Prefer Not to Say' | 'null', nullable
    - `maritalStatus` 'Single' | 'Married' | 'Divorced' | 'Widowed' | 'Separated' | 'Domestic Partnership' | 'null', nullable
    - `heightInches` integer, nullable
    - `weightPounds` integer, nullable
    - `smokerStatus` boolean, nullable
    - `postalCode` string, nullable
    - `timezone` string, nullable
    - `state` string, nullable
    - `city` string, nullable
    - `county` string, nullable
    - `countyFips` string, nullable
    - `address` string, nullable
    - `address2` string, nullable
    - `mbiNumber` string, nullable
    - `medicareCard` boolean, nullable
    - `medicarePartADate` union
      - string: Medicare Part A effective date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - ''
    - `medicarePartBDate` union
      - string: Medicare Part B effective date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - ''
    - `medicaid` boolean, nullable
    - `medicaidNumber` string, nullable
    - `socialSecurityDisability` boolean, nullable
    - `veteran` boolean, nullable
    - `vaNumber` string, nullable
    - `healthSherpaCustomerId` string, nullable
    - `householdIncome` integer, nullable
    - `annualIncome` integer, nullable
    - `filingStatus` string, nullable
    - `dependentCount` integer, nullable
    - `subsidyAmount` integer, nullable
    - `subsidyEligible` boolean, nullable
    - `existingCoverage` 'None' | 'Medicare Advantage' | 'Original Medicare' | 'Medicaid' | 'Employer' | 'Marketplace/ACA' | 'Other' | 'null', nullable
    - `existingCoveragePlanName` string, nullable
    - `existingCoverageCarrier` string, nullable
    - `desiredCoverageStartDate` union
      - string: Desired coverage start date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - ''
    - `currentSourceId` string, uuid, nullable
    - `originalSourceId` string, uuid, nullable
    - `agentName` string, nullable
    - `agentNpn` integer, nullable
    - `carrierName` string, nullable
    - `planName` string, nullable
    - `planCode` string, nullable
    - `enrollmentDate` union
      - string: Customer enrollment date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - ''
    - `effectiveDate` union
      - string: Customer coverage effective date. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
      - ''
    - `carrierAssignedCustomerId` string, nullable
    - `doNotEmail` boolean, nullable
    - `doNotMail` boolean, nullable
    - `lastContactedAt` union: Customer last contact time. ISO 8601 timestamp
      - string, date-time
      - ''
    - `convertedAt` union: Customer conversion time. ISO 8601 timestamp
      - string, date-time
      - ''
    - `testCustomer` boolean
  - `sharePhone` boolean: With relatedCustomerId: move that customer onto this customer's phone number as a related customer. They take the number's call and SMS opt-outs.
  - `isPrimaryForPhone` boolean: Make the related customer the primary contact for the shared phone number: inbound calls, texts and outreach then go to them. Both customers must share the number. Applies only when the person or link is new; a repeat request does not change the primary.

## Response `200`

POST /v2/customers/:id/related Positive response

- PostV2CustomersIdRelatedPositiveResponse
  - `outcome` 'created' | 'restored' | 'existing' | 'linked', required: created: new customer on the number. restored: a deleted customer on the number came back. existing: the person was already a customer on the number (matched by clientCustomerId, MBI, or name and date of birth), nothing was created. linked: two existing customers were linked.
  - `customer` object, required: The newly created customer record
    - `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
  - `relationship` object, nullable, required
    - `id` string, uuid, required
    - `customerId` string, uuid, required: The customer the link was added from
    - `relatedCustomerId` string, uuid, required: The customer who is the other customer's relationshipType
    - `relationshipType` 'spouse' | 'child' | 'parent' | 'sibling' | 'power_of_attorney' | 'other', required: What the related customer is to the customer in the path, for example spouse or child
    - `createdAt` string, date-time, required: Relationship creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, required: Relationship last update time. ISO 8601 timestamp

## Other responses

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