# Customers Who Share a Phone Number (/docs/guides/developers/shared-phone-numbers) A phone number can belong to more than one customer, for example a married couple or a parent and child. Each person is their own customer with their own policies. They share the number. One customer on the number is its **primary**. Inbound calls, texts and outreach go to the primary. The others are **related customers** on the same number. The flow [#the-flow] Create customers with [`POST /v2/customers`](/docs/api-reference/customers/create-customer) as usual. When the phone number already belongs to a customer, the request fails with a `409`, and you add the person to that customer instead. 1\. Create the customer [#1-create-the-customer] ``` POST https://api.carecycle.ai/v2/customers x-api-key: cc_your_api_key Content-Type: application/json ``` ```json { "firstName": "Linda", "lastName": "Hayes", "phoneNumber": "+13125550123", "dateOfBirth": "1957-03-14", "mbiNumber": "1EG4TE5MK73", "clientCustomerId": "EH-1002" } ``` 2\. Read the 409 [#2-read-the-409] ```json { "message": "A customer with this phone number already exists", "code": "CUSTOMER_ALREADY_EXISTS", "details": { "existingCustomerId": "6f1c2a9e-4b7d-4f0a-9c3e-2d8b5a7e1f40", "matchField": "phoneNumber" } } ``` Go to step 3 only when `details.matchField` is `phoneNumber`. A `409` with `matchField: "mbiNumber"` means this person already exists as a customer, so do not add them again. In rare cases a `409` has no `details`. Retry the create to get them. 3\. Add the person to the customer on that number [#3-add-the-person-to-the-customer-on-that-number] ``` POST https://api.carecycle.ai/v2/customers/6f1c2a9e-4b7d-4f0a-9c3e-2d8b5a7e1f40/related ``` ```json { "relationshipType": "spouse", "person": { "firstName": "Linda", "lastName": "Hayes", "dateOfBirth": "1957-03-14", "mbiNumber": "1EG4TE5MK73", "clientCustomerId": "EH-1002" } } ``` `person` takes the same fields as `POST /v2/customers`, except `phoneNumber`, `memberId`, `doNotCall` and `doNotSMS`. The person gets the number, the number's call and text opt-outs, and the assigned agent of the number's primary. 4\. Save the new customer's ID [#4-save-the-new-customers-id] ```json { "outcome": "created", "customer": { "id": "a3d5e7f9-1b2c-4d6e-8f0a-9b8c7d6e5f41", "firstName": "Linda", "lastName": "Hayes", "phoneNumber": "+13125550123", "isPhonePrimary": false, "...": "all other customer fields" }, "relationship": { "id": "c2b4d6f8-0a1c-4e3d-9b5a-7c6e8d0f2a13", "customerId": "6f1c2a9e-4b7d-4f0a-9c3e-2d8b5a7e1f40", "relatedCustomerId": "a3d5e7f9-1b2c-4d6e-8f0a-9b8c7d6e5f41", "relationshipType": "spouse", "createdAt": "2026-10-15T14:02:11.000Z", "updatedAt": "2026-10-15T14:02:11.000Z" } } ``` Use `customer.id` for this person from now on: updates, policies and lookups. Never look a customer up by phone number, because one number can return more than one person. Agents can move a policy that was filed under the wrong person on the number to the right one. If you then send that policy to the customer it used to be on, careCycle updates it where it is now instead of creating a copy. It is matched by `sunFireEnrollmentCode`, `healthSherpaPolicyId`, `connectureConfirmationNumber`, `applicationId`, or the carrier's ID sent as `carrierAssignedPolicyId` or `policyNumber`. Plan and effective date alone never match across people. The response's `customerId` shows who holds it. Retries are safe [#retries-are-safe] Before it adds anyone, careCycle checks the customers already on the number. A person matches when one of these is the same: 1. `mbiNumber` 2. `clientCustomerId` 3. `firstName`, `lastName` and `dateOfBirth` together On a match, nothing is created. The response returns the existing customer with `outcome: "existing"`. If the match is the customer in the path, for example a retried create for the same person, `relationship` is `null`. Every new person needs one of these, or the request fails with a `400`: `mbiNumber`, `clientCustomerId`, or `firstName`, `lastName` and `dateOfBirth` together. Send your own ID for each person as `clientCustomerId`. It is the most reliable match, and it keeps two people on one number apart. | `outcome` | Meaning | | ---------- | -------------------------------------------------------------------- | | `created` | A new customer was added to the number | | `existing` | The person was already a customer on the number. Nothing was created | | `restored` | A deleted customer on the number came back | | `linked` | Two existing customers were linked (see below) | Relationship types [#relationship-types] `relationshipType` says what the added person is to the customer in the path. Adding Linda to Robert with `child` means Linda is Robert's child. | Value | Meaning | | ------------------- | ---------------------------------------------------- | | `spouse` | Spouse or partner | | `child` | Child of the customer in the path | | `parent` | Parent of the customer in the path | | `sibling` | Sibling | | `power_of_attorney` | Holds power of attorney for the customer in the path | | `other` | Any other relationship | The type is always required. careCycle never infers a relationship from a shared phone number. Who holds the number [#who-holds-the-number] The first customer on a number stays its primary. To make the added person the primary, send `"isPrimaryForPhone": true` with the request in step 3. It applies only when the person or link is new. A repeat request that returns `existing` does not change the primary, so a change made in careCycle since then stays. To change the primary later, call [`POST /v2/customers/{id}/make-primary`](/docs/api-reference/customers/relationships/make-customer-the-phone-number-s-primary) for the customer who should hold the number. The response returns the previous primary, who is now a related customer. Customer records show the number's state: | Field | Description | | -------------------------- | -------------------------------------------------------------------------------- | | `isPhonePrimary` | `true` when this customer is the number's primary | | `phonePrimaryCustomerId` | The number's primary. Returned by `GET /v2/customers/{id}` | | `phoneNumberCustomerCount` | Customers on the number, this one included. Returned by `GET /v2/customers/{id}` | Link customers who already exist [#link-customers-who-already-exist] To link two existing customers, send `relatedCustomerId` instead of `person`: ```json { "relationshipType": "spouse", "relatedCustomerId": "a3d5e7f9-1b2c-4d6e-8f0a-9b8c7d6e5f41" } ``` Customers on different numbers can be linked. Each keeps their own number. To move the related customer onto this customer's number, add `"sharePhone": true`. They take the number's call and text opt-outs. Read and change links [#read-and-change-links] | Request | Purpose | | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | [`GET /v2/customers/{id}/relationships`](/docs/api-reference/customers/relationships/list-customer-relationships) | List a customer's links in both directions, with `sharesPhone` and `isPhonePrimary` for each person | | [`PATCH /v2/customers/{id}/relationships/{relationshipId}`](/docs/api-reference/customers/relationships/update-customer-relationship) | Change `relationshipType` | | [`DELETE /v2/customers/{id}/relationships/{relationshipId}`](/docs/api-reference/customers/relationships/remove-customer-relationship) | Remove a link. Both customers stay on their numbers, and the primary does not change | Errors [#errors] | Status | `code` | When | | ------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `VALIDATION_ERROR` | Send exactly one of `person` or `relatedCustomerId`, and a valid `relationshipType`. A `person` needs `mbiNumber`, `clientCustomerId`, or `firstName`, `lastName` and `dateOfBirth` | | `400` | `INVALID_MBI` | `mbiNumber` has no letters or digits | | `400` | `SAME_CUSTOMER` | `relatedCustomerId` is the customer in the path | | `400` | `PHONE_NOT_SHARED` | `isPrimaryForPhone` was sent for customers on different numbers | | `403` | `PHONE_PRIMARY_NOT_EDITABLE` | `isPrimaryForPhone` or make-primary, when your key can't edit the number's current primary | | `403` | `RELATED_PERSON_NOT_EDITABLE` | The person matches a customer on the number that your key can't edit | | `409` | `REVISION_CONFLICT` | A customer's phone number changed while the request ran. Retry it | | `404` | | The customer in the path or `relatedCustomerId` does not exist | | `409` | `CUSTOMER_ALREADY_EXISTS` | The person's `mbiNumber` or `clientCustomerId` belongs to a customer on another number. `details.existingCustomerId` is that customer. Link them with `relatedCustomerId` instead | Webhooks [#webhooks] [Customer webhooks](/docs/api-reference/webhooks/events#customercreated) carry `isPhonePrimary`, `phonePrimaryCustomerId` and `relationships`. A new person sends `customer.created`. Adding, changing or removing a link, and a change of primary, send `customer.updated` for both customers. A retry that changes nothing sends nothing. Match webhook customers on `id` or `externalId`, never on `phoneNumber`. Authentication [#authentication] These requests use your API key in the `x-api-key` header, like every other request. The key needs permission to edit customers.