Customers Who Share a Phone Number

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

Create customers with POST /v2/customers 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

POST https://api.carecycle.ai/v2/customers
x-api-key: cc_your_api_key
Content-Type: application/json

{
  "firstName": "Linda",
  "lastName": "Hayes",
  "phoneNumber": "+13125550123",
  "dateOfBirth": "1957-03-14",
  "mbiNumber": "1EG4TE5MK73",
  "clientCustomerId": "EH-1002"
}

2. Read the 409

{
  "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

POST https://api.carecycle.ai/v2/customers/6f1c2a9e-4b7d-4f0a-9c3e-2d8b5a7e1f40/related

{
  "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

{
  "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

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.

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.

The type is always required. careCycle never infers a relationship from a shared phone 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 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:

Link customers who already exist

To link two existing customers, send relatedCustomerId instead of person:

{
  "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

Errors

Webhooks

Customer webhooks 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

These requests use your API key in the x-api-key header, like every other request. The key needs permission to edit customers.