Generating a consultation link

This guide explains how to create consultation links that allow patients to conduct AI-assisted consultations. Patients can interact with Mindoo via chat or voice.

Prerequisites

Before you begin, make sure you have:

Completed the authentication flow and obtained a valid id_token
The read and write scopes granted to your OAuth application

Overview

Generating a consultation link involves two steps:

Create an agent

Configure a reusable consultation agent with a specific specialization

Create an invitation

Generate a unique, shareable link for a specific patient consultation

Upon creation of an invitation, you will get a URL that can be sent to the patient so that they can participate in an AI consultation.

Step 1: Create an agent

An agent defines the behavior and specialization of the AI assistant. You can reuse the same agent for multiple patient consultations.

Endpoint

POST https://api.mindoo.ai/agent
Authorization: Bearer <ID_TOKEN>
Content-Type: application/json

Request body parameters

Parameter	Required	Description
`type`	Yes	Must be `AI_CONSULTATION`
`name`	No	A human-readable name for the agent
`specialization`	No	The medical specialization (defaults to `GENERAL_PRACTICE`)
`consultationAgentType`	No	`PRE_VISIT` or `POST_VISIT` (defaults to `PRE_VISIT`)

For a list of allowed parameters, see the API reference.

Example request

curl -X POST https://api.mindoo.ai/agent \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "AI_CONSULTATION",
    "name": "Cardiology Pre-Visit",
    "specialization": "CARDIOLOGY",
    "consultationAgentType": "PRE_VISIT"
  }'

Response

A successful response returns the created agent:

{
  "id": "o7v29mgicb8mhhm9k7dw73iq",
  "type": "AI_CONSULTATION",
  "name": "Cardiology Pre-Visit",
  "specialization": "CARDIOLOGY",
  "consultationAgentType": "PRE_VISIT",
  "configurationUrl": "https://app.mindoo.ai/agent/o7v29mgicb8mhhm9k7dw73iq?token=...",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Field	Description
`id`	Unique identifier for the agent
`configurationUrl`	An authenticated URL to configure the agent's behavior in the Mindoo web app

You can use the configurationUrl to allow the healthcare professional to customize the agent's behavior. The Mindoo web app offers more ways to customize the agent than the API does.

Step 2: Create an invitation

An invitation generates a unique, shareable link for a specific patient consultation. Each invitation can only be used by one person. When an invitation URL gets visited a second time, the patient will be redirected to their existing consultation.

Endpoint

POST https://api.mindoo.ai/ai-consultation-invitation
Authorization: Bearer <ID_TOKEN>
Content-Type: application/json

Request body parameters

Parameter	Required	Description
`agentId`	Yes	The ID of the agent to use for this consultation
`patientFirstName`	No	Patient's first name (used to personalize the consultation)
`patientLastName`	No	Patient's last name
`patientDateOfBirth`	No	Patient's date of birth in `YYYY-MM-DD` format
`externalId`	No	An opaque identifier that can be used to retrieve consultations later on
`redirectUponCompletionUrl`	No	URL to redirect the patient to after completing the consultation

Example request

curl -X POST https://api.mindoo.ai/ai-consultation-invitation \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "o7v29mgicb8mhhm9k7dw73iq",
    "patientFirstName": "John",
    "patientLastName": "Doe",
    "patientDateOfBirth": "1985-03-15",
    "externalId": "patient-12345",
    "redirectUponCompletionUrl": "https://your-website.com/consultation-complete"
  }'

Response

A successful response returns the created invitation:

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

Field	Description
`id`	Unique identifier for the invitation
`invitationUrl`	The shareable link to send to the patient
`encounterId`	Initially `null`, populated once the patient starts the consultation
`redirectUponCompletionUrl`	Where the patient will be redirected after completing the consultation

You can share the invitationUrl with the patient via SMS, email, or your patient portal. The patient does not need to create an account to use this link.

What happens next

Patient opens the link

The patient clicks the invitationUrl and is presented with the AI consultation interface.

Patient starts the consultation

The patient answers questions via chat or voice. At this point, an Encounter will be created.

Patient finishes the consultation

The encounter’s status will be updated to FINISHED.

Patient is redirected

If redirectUponCompletionUrl was provided, the patient is redirected there; otherwise, they see a thank-you screen.

To retrieve the consultation results, see Retrieving consultation data.

Managing agents

List all agents

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

Get a specific agent

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

Delete an agent

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

Deleting an agent will delete associated invitations and encounters. Existing invitations will no longer work.

Managing invitations

Get an invitation

Retrieve an invitation to check its status or get the encounterId after the patient has started:

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

Delete an invitation

Revoke an invitation so it can no longer be used:

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