Insurance

Patient coverage records. PHI on subscriber fields encrypts at rest.

Plans: PPO, HMO, EPO, POS, MEDICARE, MEDICAID, SELF_PAY, OTHER. Relations: SELF, SPOUSE, CHILD, OTHER.

POST/api/insuranceBearer token

Add an insurance profile

Attach a new coverage record to a contact. Patient may have multiple — mark one isPrimary.

Required scopes:contacts.write

Request body

Name	Type	Description
`contactId`required	`string`	Patient.
`payerName`required	`string`	Insurance payer.
`planType`required	`string`	Plan type.
`memberId`required	`string`	Subscriber's member id.
`groupNumber`	`string`	Group number.
`subscriberFirstName`	`string`	Subscriber given name.
`subscriberLastName`	`string`	Subscriber family name.
`subscriberDob`	`string`	Subscriber DOB.
`relationToSubscriber`	`string`	Patient's relation to subscriber.
`cardFrontUrl`	`string`	URL to a stored image of the card front.
`cardBackUrl`	`string`	URL to a stored image of the card back.
`effectiveDate`	`string`	Coverage start (ISO 8601).
`terminationDate`	`string`	Coverage end (ISO 8601).
`isPrimary`	`boolean`	Mark as the patient's primary plan.

Request body

JSON

{ "contactId": "cln…", "payerName": "Aetna", "planType": "PPO", "memberId": "W123456789", "isPrimary": true }

Responses

201 CreatedCreated.

example

{
  "id": "ins_4k9d2x…",
  "contactId": "cln1f8s7p…",
  "payerName": "Aetna",
  "planType": "PPO",
  "memberId": "W123456789",
  "groupNumber": "00012345",
  "subscriberFirstName": "Avery",
  "subscriberLastName": "Liu",
  "relationToSubscriber": "SELF",
  "effectiveDate": "2026-01-01T00:00:00Z",
  "isPrimary": true,
  "createdAt": "2026-05-18T14:00:00Z"
}

Code samples

Shell

curl -X POST https://app.contactfollowup.com/api/insurance \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "cln…", "payerName": "Aetna", "planType": "PPO", "memberId": "W123456789", "isPrimary": true }'

GET/api/insuranceBearer token

List a contact's insurance profiles

contactId is required.

Required scopes:contacts.read

Query parameters

Name	Type	Description
`contactId`required	`string`	Contact id.

Responses

200 OKProfiles.

example

{ "profiles": [{
  "id": "ins_4k9d2x…",
  "contactId": "cln1f8s7p…",
  "payerName": "Aetna",
  "planType": "PPO",
  "memberId": "W123456789",
  "groupNumber": "00012345",
  "subscriberFirstName": "Avery",
  "subscriberLastName": "Liu",
  "relationToSubscriber": "SELF",
  "effectiveDate": "2026-01-01T00:00:00Z",
  "isPrimary": true,
  "createdAt": "2026-05-18T14:00:00Z"
}] }

400 Bad RequestMissing contactId.

Code samples

Shell

curl -X GET https://app.contactfollowup.com/api/insurance \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json"