TxCases V1 — Developer Guide

Returns a paginated list of treatment cases matching the filter criteria.

✅ Recommended: Use lastId with pageSize. Combine with lastModified and patient.id to keep queries narrow.

patient.id== resolves to cases on that patient's treatment plan. If the patient has no plan in the organization, the result is empty (200 / data: []).

⚠️ Date-limiting filters: If you omit a date-limiting filter such as lastModified, one may be applied automatically. Supply your own date bound for predictable results.

⚠️ Narrow your query: A very wide lastModified range with no patient.id can return 408 on large tenants.

Ordering: Bulk GET does not apply a lastModified sort. lastId means id > previousId. Pass the largest id from the previous page.

Empty results: 200 with data: [] means no cases matched; it does not indicate invalid filter values.

When lastId is present, meta.pagination.total is omitted. Use total count when you need a count. See Bulk GET — Total Count Behavior.

Cases for a patient modified after a date:

GET /api/v1/txcases?pageSize=100&filter=patient.id==12000006542062,lastModified>=2025-01-01T00:00:00Z

Cases for one patient only:

GET /api/v1/txcases?pageSize=100&filter=patient.id==12000006542062

Subset of fields:

GET /api/v1/txcases?responseFields=name,status,patient&filter=patient.id==12000006542062

Next page — send lastId as the largest id from the previous data array (not the last row if that row is not the max id):

GET /api/v1/txcases?pageSize=100&lastId=9000000000123&filter=patient.id==12000006542062,lastModified>=2025-01-01T00:00:00Z

Returns a single treatment case. Missing or non-numeric txCaseId → 404.

Full case:

GET /api/v1/txcases/9000000000123

Subset of fields:

GET /api/v1/txcases/9000000000123?responseFields=name,status,patient

Creates a treatment case. Returns 201 with the created resource in data.

Side effects: Creating a case also creates a treatment option and a first visit (duration 60) that contains the supplied patient procedures. Those procedures are not returned on the TxCase body — list visits with filter=txCase.id==<id>.

Linked-model writes are { "id": … } only. Do not send url or type.

providerSignatureDate and witnessSignatureDate are set when the matching signature is sent. Do not write those dates.

POST /api/v1/txcases
Content-Type: application/json

{
  "user": { "id": 12000006542001 },
  "patient": { "id": 12000006542062 },
  "name": "Recommended treatment",
  "procedures": [{ "id": 8000000000456 }]
}

POST /api/v1/txcases
Content-Type: application/json

{
  "user": { "id": 12000006542001 },
  "patient": { "id": 12000006542062 },
  "name": "Present at next recare",
  "procedures": [{ "id": 8000000000456 }],
  "note": "Discuss crown vs implant",
  "showNote": true,
  "expirationDate": "2026-12-31",
  "showExpirationDate": false,
  "status": "PRESENTED"
}

POST /api/v1/txcases
Content-Type: application/json

{
  "user": { "id": 12000006542001 },
  "patient": { "id": 12000006542062 },
  "name": "Signed case",
  "procedures": [{ "id": 8000000000456 }],
  "providerSignature": { "id": 7000000000100 },
  "witnessSignature": { "id": 7000000000101 }
}

The response includes providerSignatureDate and witnessSignatureDate. Do not send those dates.

A second POST with the same name for the same patient:

POST /api/v1/txcases
Content-Type: application/json

{
  "user": { "id": 12000006542001 },
  "patient": { "id": 12000006542062 },
  "name": "Recommended treatment",
  "procedures": [{ "id": 8000000000457 }]
}

Returns 400 with source name.

Practice procedure ids (or a missing id) are rejected. Each element must be a patient procedure:

{
  "user": { "id": 12000006542001 },
  "patient": { "id": 12000006542062 },
  "name": "Bad procedures",
  "procedures": [{ "id": "a" }]
}

Returns 400 with source procedures.

Updates the case identified by txCaseId. Only included properties change. Missing case → 404.

user is frozen after create — omit it on PUT.

Sending the already saved status is a no-op: 200, and status may be omitted from the response.

PUT /api/v1/txcases/9000000000123
Content-Type: application/json

{
  "note": "Accepted at consult",
  "status": "ACCEPTED"
}

PUT /api/v1/txcases/9000000000123
Content-Type: application/json

{
  "name": "Accepted treatment plan"
}

Duplicate name on the same patient plan → 400.

PUT /api/v1/txcases/9000000000123
Content-Type: application/json

{
  "expirationDate": "2026-12-31",
  "showExpirationDate": true
}

PUT /api/v1/txcases/9000000000123
Content-Type: application/json

{
  "providerSignature": { "id": 7000000000100 },
  "witnessSignature": { "id": 7000000000101 }
}

If the case is already ACCEPTED:

PUT /api/v1/txcases/9000000000123
Content-Type: application/json

{
  "status": "ACCEPTED"
}

Returns 200. status may be omitted from the response.

Deletes the case. Query deleteType is required. Missing or invalid deleteType → 400. Missing case → 404.

DELETE /api/v1/txcases/9000000000123?deleteType=DELETE

DELETE /api/v1/txcases/9000000000123?deleteType=MOVE_AND_DELETE

DELETE /api/v1/txcases/9000000000123

DELETE /api/v1/txcases/9000000000123?deleteType=INVALID_TYPE

Returns isCompleted for one or more cases. filter and responseFields are required. ALL is not valid.

isCompleted is true when the case’s patient procedures are completed.

Empty responseFields or an unknown name → 400.

GET /api/v1/txcases/calculated?filter=ids->[9000000000123,9000000000124]&responseFields=isCompleted

Missing responseFields → 400:

GET /api/v1/txcases/calculated?filter=ids->[9000000000123]

ALL is not valid → 400:

GET /api/v1/txcases/calculated?filter=ids->[9000000000123]&responseFields=ALL

Same calculated fields for one case. Missing txCaseId → 404. Missing responseFields → 400.

GET /api/v1/txcases/9000000000123/calculated?responseFields=isCompleted

Missing responseFields → 400:

GET /api/v1/txcases/9000000000123/calculated

Returns fee totals for the case and a row per visit. Missing case → 404.

The case total field is caseTotal (not caseAmount).

visitId, code, Th, surface, description, provider, amount, discount, guarantorPortion

GET /api/v1/txcases/9000000000123/amount

Returns { "totalCount": <integer> } for cases matching the same filters as bulk GET (patient.id, lastModified).

Document only Organization-ID and filter. Pagination query parameters are not used on this path.

Count for one patient:

GET /api/v1/txcases/totalcount?filter=patient.id==12000006542062

Count with a date bound:

GET /api/v1/txcases/totalcount?filter=patient.id==12000006542062,lastModified>=2025-01-01T00:00:00Z

See Bulk GET — Total Count Behavior.

For real-time case creates, updates, and deletes, use StreamAPI webhooks (SNS) instead of polling bulk GET. Setup: Creating and Setting Up Webhooks for the StreamAPI.

Domain type TxCaseV1. Operations: CREATE, UPDATE, DELETE.

Creating a case also creates a visit (see Visits V1), which can emit a separate VisitV1 CREATE event.

A successful 200/201 response returns:

Bulk GET data is an array and includes meta.pagination (limit, offset, and total when present).

Invalid body or query. Common causes: missing required create fields, duplicate name, invalid procedures linked models, missing or invalid deleteType, empty or unknown calculated responseFields (including ALL), invalid status.

No case for txCaseId in this organization, or the path id is not a valid numeric id.

Error: TxCase with name '…' already exists

Error: Each element must be an object with an id of PatientProcedureV1

Error: deleteType must have a value in [DELETE,MOVE_AND_DELETE]

Error: List of calculated fields should not be empty / field does not exist

Error: status should not be empty / invalid enum