Providers

Practitioners who see patients — physicians, NPs, therapists. Required to create appointments.

A provider may or may not have a ContactFollowUp user account attached. Linking to a user lets that person view their own schedule in the staff app.

POST/api/providersBearer token (ADMIN)

Create a provider

ADMIN-only — providers are workspace-wide and gate appointment scheduling.

Required scopes:users.manage

Request body

Name	Type	Description
`displayName`required	`string`	Provider name.
`role`required	`string`	Specialty / title. 1–40 chars.
`npiNumber`	`string`	National Provider Identifier.
`userId`	`string`	Optional linked ContactFollowUp user.
`photoUrl`	`string`	Public photo URL.
`bio`	`string`	Patient-facing bio. ≤ 4000 chars.
`timezone`	`string`	IANA timezone for scheduling.
`active`	`boolean`	Whether bookable.

Request body

JSON

{ "displayName": "Dr. Sasha Mendez", "role": "Family Medicine" }

Responses

201 CreatedCreated.

example

{
  "id": "prv_9k4w2x…",
  "displayName": "Dr. Sasha Mendez",
  "role": "Family Medicine",
  "npiNumber": "1234567890",
  "userId": "usr_8h2c3p…",
  "photoUrl": null,
  "bio": "Board-certified family medicine, 12 years.",
  "timezone": "America/New_York",
  "active": true,
  "createdAt": "2026-05-18T14:00:00Z"
}

Code samples

Shell

curl -X POST https://app.contactfollowup.com/api/providers \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "Dr. Sasha Mendez", "role": "Family Medicine" }'

GET/api/providersBearer token

List providers

Active and inactive providers.

Required scopes:contacts.read

Query parameters

Name	Type	Description
`active`	`boolean`	Restrict to active providers (true).

Responses

200 OKProviders.

example

{ "providers": [{
  "id": "prv_9k4w2x…",
  "displayName": "Dr. Sasha Mendez",
  "role": "Family Medicine",
  "npiNumber": "1234567890",
  "userId": "usr_8h2c3p…",
  "photoUrl": null,
  "bio": "Board-certified family medicine, 12 years.",
  "timezone": "America/New_York",
  "active": true,
  "createdAt": "2026-05-18T14:00:00Z"
}] }

Code samples

Shell

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