Dental PMS

Revenue

17 endpoints

get/api/v1/{org_id}/revenue-iq/fields

Get filter field registry

Return the complete filter field registry. Contains all available fields grouped by category, with their operators, value sources, and scope information. Used by the filter builder UI to render the field picker.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
categoriesobject[]required

All field categories with their fields.

scopesobject[]

Scope definitions.

snapshot_hashstringrequired

Stable hash of the field registry meaning used for drift detection.

source_versionstringrequired

PMS-owned field registry snapshot contract version.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/revenue-iq/fields" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/revenue-iq/lists

List smart lists

List smart lists accessible to the current user. Supports filtering by scope, type, pinned status, and name search.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
scopestring

Filter by visibility scope.

list_typestring

Filter by list type.

searchstring

Case-insensitive name search.

is_pinnedboolean

Filter by pinned status.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 25

Responses

200Successful Response
itemsobject[]required

Smart list items.

pageintegerrequired

Current page number.

page_sizeintegerrequired

Items per page.

totalintegerrequired

Total number of matching lists.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/revenue-iq/lists" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/revenue-iq/lists/{list_uuid}

Get smart list

Get a single smart list by UUID. Raises 404 if the list does not exist or is soft-deleted.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
base_versionintegerrequired

Current version for optimistic concurrency.

created_atstring (date-time)required

Timestamp when the list was created.

descriptionstring
filter_definitionobject

Complete filter definition stored on a smart list. Structure: groups joined by OR, conditions within groups joined by AND. Produces queries like: ``(A AND B) OR (C AND D)``.

idstring (uuid)required

Unique identifier of the smart list.

is_pinnedbooleanrequired

Whether the list is pinned to the user's sidebar.

last_executed_atstring (date-time)
last_result_countinteger
list_typeenumrequired

List type. One of: dynamic, static, preset.

dynamicpresetstatic
namestringrequired

Display name of the smart list.

ownerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

preset_keystring
scopeenumrequired

Visibility scope. One of: organization, location, personal.

locationorganizationpersonal
scope_locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

sort_orderintegerrequired

Display sort order in the sidebar.

tagsstring[]

User-defined tags for organizing lists.

updated_atstring (date-time)required

Timestamp when the list was last modified.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/revenue-iq/presets

Get preset templates

Return all available preset list templates. Presets are system-defined smart list configurations that can be used as starting points for new lists.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/revenue-iq/presets" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/revenue-iq/compose

Compose filter from natural language

Translate a natural language query into a filter definition. Not yet implemented — returns a stub response until LLM integration is wired. The endpoint will use the field registry schema to constrain the AI-generated filter. Raises 422 if query is empty or too short.

Parameters

Path Parameters
org_idstringrequired

Request Body

contextobject

Optional context for AI composition. Narrows the field catalog and value options provided to the LLM.

querystringrequired

Natural language query to translate into a filter definition.

Responses

200Successful Response
confidencenumberrequired

Confidence score (0.0 to 1.0) for the generated filter.

explanationstringrequired

Human-readable explanation of the generated filter.

field_keys_usedstring[]

List of field keys used in the generated filter.

filter_definitionobject

Complete filter definition stored on a smart list. Structure: groups joined by OR, conditions within groups joined by AND. Produces queries like: ``(A AND B) OR (C AND D)``.

warningsstring[]

Warnings about the generated filter, e.g., scoped conditions split across groups or assumptions made during composition.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/compose" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "context": null,
    "query": "string"
  }'
post/api/v1/{org_id}/revenue-iq/count

Count filter matches

Quick count of patients matching a filter definition. Faster than a full execute — returns only the count and timing.

Parameters

Path Parameters
org_idstringrequired

Request Body

expected_source_snapshot_versionstringrequired

Revenue IQ field-registry snapshot hash used to compose the filter. PMS rejects the count before execution if its current registry snapshot differs.

filter_definitionobjectrequired

The filter definition to count matches for.

Responses

200Successful Response
countintegerrequired

Number of patients matching the filter.

execution_time_msintegerrequired

Server-side query execution time in milliseconds.

source_snapshot_versionstringrequired

Stable Revenue IQ field-registry snapshot hash used for execution. Consumers must compare this with the snapshot used to compose the filter.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/count" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_source_snapshot_version": "string",
    "filter_definition": {}
  }'
post/api/v1/{org_id}/revenue-iq/execute

Execute ad-hoc filter

Execute an ad-hoc filter definition without saving. Useful for previewing results while building a filter.

Parameters

Path Parameters
org_idstringrequired

Request Body

expected_source_snapshot_versionstring
filter_definitionobjectrequired

The filter definition to execute.

pageinteger

Page number.

page_sizeinteger

Rows per page.

sort_bystring

Sort field.

sort_direnum

Sort direction.

ascdesc

Responses

200Successful Response
execution_time_msintegerrequired

Query execution time (ms).

pageintegerrequired

Current page.

page_sizeintegerrequired

Rows per page.

patientsobject[]required

Paginated patient rows.

source_snapshot_versionstringrequired

Stable Revenue IQ field-registry snapshot hash used for execution. Agent-MS compares this with the snapshot used for filter composition.

total_countintegerrequired

Total matching patients.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/execute" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_source_snapshot_version": "string",
    "filter_definition": {},
    "page": 1,
    "page_size": 50,
    "sort_by": "last_name"
  }'
post/api/v1/{org_id}/revenue-iq/lists

Create smart list

Create a new smart list (dynamic or static). Dynamic lists require a filter_definition. Static lists manage membership via the /members endpoints. Preset lists are system-seeded and cannot be created through this endpoint. Raises 409 if a list with the same name already exists for this owner/scope. Raises 422 if filter_definition is missing for dynamic lists. Raises 422 if scope_location_uuid is missing when scope is 'location'.

Parameters

Path Parameters
org_idstringrequired

Request Body

descriptionstring
filter_definitionobject

Complete filter definition stored on a smart list. Structure: groups joined by OR, conditions within groups joined by AND. Produces queries like: ``(A AND B) OR (C AND D)``.

is_pinnedboolean

Whether to pin the list to the sidebar.

list_typeenumrequired

List type. One of: dynamic (query-based), static (manual membership). Preset lists are system-seeded and cannot be created via the API.

dynamicstatic
namestringrequired

Display name for the list.

scopeenumrequired

Visibility scope.

locationorganizationpersonal
scope_location_uuidstring (uuid)
tagsstring[]

User-defined tags.

Responses

201Successful Response
base_versionintegerrequired

Current version for optimistic concurrency.

created_atstring (date-time)required

Timestamp when the list was created.

descriptionstring
filter_definitionobject

Complete filter definition stored on a smart list. Structure: groups joined by OR, conditions within groups joined by AND. Produces queries like: ``(A AND B) OR (C AND D)``.

idstring (uuid)required

Unique identifier of the smart list.

is_pinnedbooleanrequired

Whether the list is pinned to the user's sidebar.

last_executed_atstring (date-time)
last_result_countinteger
list_typeenumrequired

List type. One of: dynamic, static, preset.

dynamicpresetstatic
namestringrequired

Display name of the smart list.

ownerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

preset_keystring
scopeenumrequired

Visibility scope. One of: organization, location, personal.

locationorganizationpersonal
scope_locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

sort_orderintegerrequired

Display sort order in the sidebar.

tagsstring[]

User-defined tags for organizing lists.

updated_atstring (date-time)required

Timestamp when the list was last modified.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/lists" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "string",
    "filter_definition": null,
    "is_pinned": false,
    "list_type": "dynamic",
    "name": "string",
    "scope": "location"
  }'
post/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/actions/create-tasks

Create outreach tasks

Create one outreach task per patient in the list. Not yet implemented — returns 501 until Phase 2. Raises 404 if the list does not exist.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Request Body

assigned_to_uuidstring (uuid)required

UUID of the user to assign the tasks to.

due_datestring (date)
priorityenum

Task priority.

highlowmedium
task_templatestringrequired

Task description template. Supports placeholders: {patient_name}, {phone}, {recall_date}.

Responses

200Successful Response
assigned_toobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

tasks_createdintegerrequired

Number of tasks created.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/actions/create-tasks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_to_uuid": "00000000-0000-0000-0000-000000000000",
    "due_date": "string",
    "priority": "high",
    "task_template": "string"
  }'
post/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/actions/export

Export list results

Export list results to CSV or XLSX. Not yet implemented — returns 501 until Phase 2. Raises 404 if the list does not exist.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Request Body

columnsstring[]required

PatientListItemOut fields to include as columns.

formatenum

Export file format.

csvxlsx

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/actions/export" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [],
    "format": "csv"
  }'
post/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/actions/tag

Bulk-tag list patients

Apply tag add/remove to all patients in the list. Not yet implemented — returns 501 until Phase 2. Raises 404 if the list does not exist.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Request Body

actionenumrequired

Whether to add or remove the specified tags.

addremove
tag_uuidsstring (uuid)[]required

Patient tag definition UUIDs. Max 20 per request.

Responses

200Successful Response
patients_affectedintegerrequired

Number of patients whose tags were modified.

tags_appliedintegerrequired

Number of tag assignments created or removed.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/actions/tag" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "tag_uuids": []
  }'
post/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/duplicate

Duplicate smart list

Duplicate a smart list with ' (Copy)' suffix. The new list is owned by the requesting user. Preset lists are converted to dynamic on duplication. Raises 404 if the source list does not exist.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Responses

201Successful Response
base_versionintegerrequired

Current version for optimistic concurrency.

created_atstring (date-time)required

Timestamp when the list was created.

descriptionstring
filter_definitionobject

Complete filter definition stored on a smart list. Structure: groups joined by OR, conditions within groups joined by AND. Produces queries like: ``(A AND B) OR (C AND D)``.

idstring (uuid)required

Unique identifier of the smart list.

is_pinnedbooleanrequired

Whether the list is pinned to the user's sidebar.

last_executed_atstring (date-time)
last_result_countinteger
list_typeenumrequired

List type. One of: dynamic, static, preset.

dynamicpresetstatic
namestringrequired

Display name of the smart list.

ownerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

preset_keystring
scopeenumrequired

Visibility scope. One of: organization, location, personal.

locationorganizationpersonal
scope_locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

sort_orderintegerrequired

Display sort order in the sidebar.

tagsstring[]

User-defined tags for organizing lists.

updated_atstring (date-time)required

Timestamp when the list was last modified.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/duplicate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/execute

Execute smart list

Execute a saved smart list's filter against the patient database. Returns paginated patient results with execution timing. Raises 404 if the list does not exist or is soft-deleted.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Request Body

pageinteger

Page number (1-indexed).

page_sizeinteger

Rows per page. Max 200.

sort_bystring

Sort field. One of: last_name, first_name, chart_number, date_of_birth, status, estimated_balance, created_at. Invalid values default to last_name.

sort_direnum

Sort direction.

ascdesc

Responses

200Successful Response
execution_time_msintegerrequired

Query execution time (ms).

listobjectrequired

Summary of the smart list that was executed.

pageintegerrequired

Current page.

page_sizeintegerrequired

Rows per page.

patientsobject[]required

Paginated patient rows.

total_countintegerrequired

Total matching patients.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/execute" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 50,
    "sort_by": "last_name",
    "sort_dir": "asc"
  }'
post/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/members

Add static list members

Add patients to a static list. Duplicate patients are silently ignored (idempotent). Raises 400 if the list is dynamic or preset. Raises 404 if the list or any patient UUID does not exist.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Request Body

notesstring
patient_uuidsstring (uuid)[]required

Patient UUIDs to add. Max 500 per request.

Responses

200Successful Response
added_countintegerrequired

Number of patients actually added (excludes duplicates).

removed_countintegerrequired

Number of patients actually removed.

total_membersintegerrequired

Total member count after the operation.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/members" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "string",
    "patient_uuids": []
  }'
patch/api/v1/{org_id}/revenue-iq/lists/{list_uuid}

Update smart list

Update a smart list. Only provided fields are updated. The list_type, scope, and scope_location fields are immutable after creation. Raises 400 if filter_definition is set on a static list. Raises 404 if the list does not exist. Raises 409 if base_version does not match (optimistic concurrency).

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

descriptionstring
filter_definitionobject

Complete filter definition stored on a smart list. Structure: groups joined by OR, conditions within groups joined by AND. Produces queries like: ``(A AND B) OR (C AND D)``.

is_pinnedboolean
namestring
sort_orderinteger
tagsstring[]

Responses

200Successful Response
base_versionintegerrequired

Current version for optimistic concurrency.

created_atstring (date-time)required

Timestamp when the list was created.

descriptionstring
filter_definitionobject

Complete filter definition stored on a smart list. Structure: groups joined by OR, conditions within groups joined by AND. Produces queries like: ``(A AND B) OR (C AND D)``.

idstring (uuid)required

Unique identifier of the smart list.

is_pinnedbooleanrequired

Whether the list is pinned to the user's sidebar.

last_executed_atstring (date-time)
last_result_countinteger
list_typeenumrequired

List type. One of: dynamic, static, preset.

dynamicpresetstatic
namestringrequired

Display name of the smart list.

ownerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

preset_keystring
scopeenumrequired

Visibility scope. One of: organization, location, personal.

locationorganizationpersonal
scope_locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

sort_orderintegerrequired

Display sort order in the sidebar.

tagsstring[]

User-defined tags for organizing lists.

updated_atstring (date-time)required

Timestamp when the list was last modified.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "description": "string",
    "filter_definition": null,
    "is_pinned": null,
    "name": "string"
  }'
delete/api/v1/{org_id}/revenue-iq/lists/{list_uuid}

Delete smart list

Soft-delete a smart list. Raises 404 if the list does not exist or is already deleted.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
base_versionintegerrequired

Current version for optimistic concurrency.

created_atstring (date-time)required

Timestamp when the list was created.

descriptionstring
filter_definitionobject

Complete filter definition stored on a smart list. Structure: groups joined by OR, conditions within groups joined by AND. Produces queries like: ``(A AND B) OR (C AND D)``.

idstring (uuid)required

Unique identifier of the smart list.

is_pinnedbooleanrequired

Whether the list is pinned to the user's sidebar.

last_executed_atstring (date-time)
last_result_countinteger
list_typeenumrequired

List type. One of: dynamic, static, preset.

dynamicpresetstatic
namestringrequired

Display name of the smart list.

ownerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

preset_keystring
scopeenumrequired

Visibility scope. One of: organization, location, personal.

locationorganizationpersonal
scope_locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

sort_orderintegerrequired

Display sort order in the sidebar.

tagsstring[]

User-defined tags for organizing lists.

updated_atstring (date-time)required

Timestamp when the list was last modified.

422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/members

Remove static list members

Remove patients from a static list. Raises 400 if the list is dynamic or preset. Raises 404 if the list does not exist.

Parameters

Path Parameters
list_uuidstringrequired
org_idstringrequired

Request Body

patient_uuidsstring (uuid)[]required

Patient UUIDs to remove. Max 500 per request.

Responses

200Successful Response
added_countintegerrequired

Number of patients actually added (excludes duplicates).

removed_countintegerrequired

Number of patients actually removed.

total_membersintegerrequired

Total member count after the operation.

422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/revenue-iq/lists/{list_uuid}/members" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uuids": []
  }'