Retrieving consultation data

This guide explains how to retrieve consultation data after a patient has completed an AI-assisted interview. You can access encounter metadata and download PDF reports.

Prerequisites

Before you begin, make sure you have:

1. Completed the authentication flow and obtained a valid id_token
2. The read scope granted to your OAuth application
3. Created an invitation and had a patient complete a consultation (see Generating a consultation link)

Overview

After a patient completes a consultation, you can:

Understanding encounters

An encounter represents a completed or in-progress patient consultation. Each encounter contains:

Encounter statuses

Regardless of the encounter status, you will be able to retrieve the corresponding information. Some information, such as the transcript and report, will be partial while the encounter is still ongoing.

List all encounters

Retrieve all encounters for your organization.

Endpoint

GET https://api.mindoo.ai/encounter
Authorization: Bearer <ID_TOKEN>

Example request

curl -X GET https://api.mindoo.ai/encounter \
  -H "Authorization: Bearer <ID_TOKEN>"

Response

[
  {
    "id": "enc123abc456def789ghi012",
    "type": "CONSULT",
    "status": "FINISHED",
    "modality": "SPEECH",
    "locale": "en-US",
    "createdAt": "2025-01-15T11:00:00.000Z"
  },
  {
    "id": "enc789xyz123abc456def012",
    "type": "CONSULT",
    "status": "ONGOING",
    "modality": "TEXT",
    "locale": "nl-NL",
    "createdAt": "2025-01-15T11:30:00.000Z"
  }
]

Get a specific encounter

Retrieve details about a specific encounter using its ID.

Endpoint

GET https://api.mindoo.ai/encounter/{id}
Authorization: Bearer <ID_TOKEN>

Example request

curl -X GET https://api.mindoo.ai/encounter/<ENCOUNTER_ID> \
  -H "Authorization: Bearer <ID_TOKEN>"

Response

{
  "id": "enc123abc456def789ghi012",
  "type": "CONSULT",
  "status": "FINISHED",
  "modality": "SPEECH",
  "locale": "en-US",
  "createdAt": "2025-01-15T11:00:00.000Z"
}

Finding the encounter ID

There are two ways to find the encounter ID for a consultation:

From the invitation

After a patient starts a consultation, the invitation's encounterId field is populated:

curl -X GET https://api.mindoo.ai/consult-invitation/<INVITATION_ID> \
  -H "Authorization: Bearer <ID_TOKEN>"

Response:

{
  "agentId": "o7v29mgicb8mhhm9k7dw73iq",
  "createdAt": "2025-01-15T10:35:00.000Z",
  "id": "abc123def456ghi789jkl012",
  "invitationUrl": "https://app.mindoo.ai/consult/abc123def456ghi789jkl012",
  "encounterCompletionLinkText": "Back to calendar",
  "encounterCompletionLinkUrl": "https://your-website.com/consultation-complete",
  "encounterId": "enc123abc456def789ghi012"
}

From the encounter list

If you provided an externalId when creating the invitation, you can use it to correlate encounters with your internal records by listing all encounters and matching them.

Download the report

You can download a PDF report summarizing the consultation.

Endpoint

GET https://api.mindoo.ai/report/{id}
Authorization: Bearer <ID_TOKEN>

The {id} parameter is the encounter ID.

Example request

curl -X GET https://api.mindoo.ai/report/<ENCOUNTER_ID> \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -o report.pdf

Response

The response is a PDF file (application/pdf) containing:

• Patient information (if provided when creating the invitation)
• Summary of the consultation
• Key findings and symptoms reported
• Relevant medical history discussed

Delete an encounter

Remove an encounter and its associated data.

Endpoint

DELETE https://api.mindoo.ai/encounter/{id}
Authorization: Bearer <ID_TOKEN>

Example request

curl -X DELETE https://api.mindoo.ai/encounter/<ENCOUNTER_ID> \
  -H "Authorization: Bearer <ID_TOKEN>"

A successful deletion returns a 204 No Content response.

Deletion and cascading behavior

When deleting resources via the API, related data is automatically cleaned up through database cascading rules. Understanding these cascades helps you predict what data is removed and what is preserved.

Deleting an invitation

curl -X DELETE https://api.mindoo.ai/consult-invitation/<INVITATION_ID> \
  -H "Authorization: Bearer <ID_TOKEN>"

Deleting a consult invitation only removes the invitation itself. If the patient has already started a consultation, the encounter and all its data (report, transcript, patient information) are preserved. The link between the encounter and the invitation is cleared (set to null).

Deleting an encounter

curl -X DELETE https://api.mindoo.ai/encounter/<ENCOUNTER_ID> \
  -H "Authorization: Bearer <ID_TOKEN>"

Deleting an encounter removes the encounter and all data directly tied to it:

Deleting an agent

curl -X DELETE https://api.mindoo.ai/agent/<AGENT_ID> \
  -H "Authorization: Bearer <ID_TOKEN>"

Deleting an agent removes the agent configuration and its invitations, but does not delete existing encounters:

Because invitations are deleted, any invitation URLs that haven't been used yet will stop working. However, consultations that have already started or finished remain accessible.

Summary

The following diagram shows how deletions propagate:

Agent ──(cascade)──→ Invitations
   │                      │
   │                      └──(set null)──→ Encounters (preserved)
   └──(set null)──→ Encounters (preserved)

Encounter ──(cascade)──→ Report
    │                 ──→ Transcript
    │                 ──→ Patient consultation data
    │                 ──→ Audio recordings
    │                 ──→ Labels
    │                 ──→ Encounter-scoped files
    │
    └── Invitation (preserved, unmodified)

Invitation ──→ Encounters (preserved, unmodified)

In short: deleting an invitation or an agent never deletes encounters. Only explicitly deleting an encounter removes its associated consultation data.

Typical integration workflow

Here's a typical workflow for integrating consultation data into your system: