Documents V1 — Developer Guide

Returns a paginated list of documents in your organization matching the filter criteria.

⚠️ Rate Limited: This endpoint is rate limited. See the rate limiting guide for details.

If filter is omitted, all documents in the organization are returned (subject to pagination). No automatic date filter is applied.

Note on ownerOrganization.id: Filtering by organization owner matches documents whose owner type is Organization only. Documents owned by a patient or perio exam are not included, even when scoped to the same organization.

The -> operator accepts an array of tag names (IN semantics). Tag names containing commas or special characters can be quoted inside the array.

?filter=tags->[macaco,"tag, with, comma"]

List all documents for a patient:

GET /api/v1/documents?filter=ownerPatient.id==12000006542062

Find documents tagged Insurance:

GET /api/v1/documents?filter=tags->[Insurance]

Use lastId with pageSize to page through results. The API returns documents with id greater than the cursor value (id > lastId), in ascending ID order.

Send your first request without lastId:

GET /api/v1/documents?pageSize=100&filter=ownerPatient.id==12000006542062

Take the id of the last record in the returned data array and pass it as lastId in the next request:

GET /api/v1/documents?lastId=1000000020702&pageSize=100&filter=ownerPatient.id==12000006542062

Continue until the response returns an empty data array.

Use the same filter on every page so the cursor stays consistent across the full result set.

Returns the number of documents matching a filter. Uses the same filter syntax as bulk GET.

Relationship to bulk GET: Applying the same filter to both endpoints returns a count and records for the same set of documents.

Same as GET — Bulk List Documents: ownerOrganization.id, ownerPatient.id, ownerPerioExam.id, tags.

Count documents for a patient:

GET /api/v1/documents/totalcount?filter=ownerPatient.id==12000006542062

Count documents with a specific tag:

GET /api/v1/documents/totalcount?filter=tags->[Insurance]

Returns a single document by its ID, including signed URLs in storage for downloading file content.

GET /api/v1/documents/1000000020702

Creates a new document with file content supplied as base64 in the request body. Returns 201 with the created document in data.

All creates require name, mimeType, and file.content. Provide at most one owner field (ownerOrganization, ownerPatient, or ownerPerioExam). If none is provided, the document is assigned to the requesting organization.

MIME alias: JPG, JPE, JIF, JFIF, and JFI are normalized to JPEG.

{
  "name": "office-policy",
  "mimeType": "PDF",
  "file": {
    "content": "JVBERi0xLjQKJeLjz9MKMy..."
  }
}

{
  "data": {
    "id": 1000000020702,
    "name": "office-policy.pdf",
    "mimeType": "PDF",
    "ownerType": "Organization",
    "ownerOrganization": { "id": "1006" },
    "storage": { "original": "https://..." }
  }
}

{
  "name": "consent-form",
  "mimeType": "PDF",
  "ownerPatient": { "id": 12000006542062 },
  "file": {
    "content": "JVBERi0xLjQKJeLjz9MKMy..."
  }
}

{
  "name": "perio-chart",
  "mimeType": "PDF",
  "ownerPerioExam": { "id": 9876543210 },
  "file": {
    "content": "JVBERi0xLjQKJeLjz9MKMy..."
  }
}

{
  "name": "xray",
  "mimeType": "JPEG",
  "ownerPatient": { "id": 12000006542062 },
  "file": {
    "content": "/9j/4AAQSkZJRgABAQAA...",
    "fromX": 0,
    "fromY": 0,
    "width": 800,
    "height": 600,
    "ratio": 1.0
  }
}

{
  "name": "insurance-eob",
  "mimeType": "PDF",
  "ownerPatient": { "id": 12000006542062 },
  "tags": ["Insurance", "EOB"],
  "file": {
    "content": "JVBERi0xLjQKJeLjz9MKMy..."
  }
}

Updates an existing document. Only name and tags can be changed; file content, mimeType, and owner cannot be updated via this endpoint.

Returns 200 with the updated document in data. The server appends the file extension to name on update (same as create).

PUT /api/v1/documents/1000000020702

{
  "name": "updated-consent",
  "tags": ["Legal", "Signed"]
}

Permanently deletes a document, its stored file content, and tag associations. Unreferenced tags are removed. If this was the last document for an owner, the owner record is also removed.

Returns 200 with the deleted document ID in data.

DELETE /api/v1/documents/1000000020702

{
  "data": {
    "id": "1000000020702"
  }
}

Documents are streamable via the Streaming API. The domain type is DocumentV1.

Tag changes are reflected through document CREATE, UPDATE, and DELETE events — there is no separate tag stream domain.

organizationId.locationId.DocumentV1.operationType

Listen for all document events across all locations:

66d22762060811049b50d085.*.DocumentV1.*

Listen for creates only:

66d22762060811049b50d085.*.DocumentV1.CREATE

Listen for deletes at a specific location:

66d22762060811049b50d085.1000000000123.DocumentV1.DELETE

The request body or parameters are invalid. See field-level errors below.

Error: Missing or invalid name.

Error: Invalid mimeType.

Error: Missing or invalid file content.

Error: Multiple or invalid owner fields.

Error: Invalid tag value.

Error: Invalid filter.