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 `CONSULT`
`name`	No	A human-readable name for the agent
`specialization`	No	The medical specialization (defaults to `GENERAL_PRACTICE`)
`consultAgentType`	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": "CONSULT",
    "name": "Cardiology Pre-Visit",
    "specialization": "CARDIOLOGY",
    "consultAgentType": "PRE_VISIT"
  }'

Response

A successful response returns the created agent:

{
  "id": "o7v29mgicb8mhhm9k7dw73iq",
  "type": "CONSULT",
  "name": "Cardiology Pre-Visit",
  "specialization": "CARDIOLOGY",
  "consultAgentType": "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 app

You can use the configurationUrl to allow the healthcare professional to customize the agent's behavior. The Mindoo 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/consult-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
`encounterCompletionLinkText`	No	Text label for a hyperlink shown to the patient after completing the consultation
`encounterCompletionLinkUrl`	No	URL for a hyperlink shown to the patient after completing the consultation
`externalId`	No	An opaque identifier that can be used to retrieve consultations later on
`patientDateOfBirth`	No	Patient's date of birth in `YYYY-MM-DD` format
`patientFirstName`	No	Patient's first name (used to personalize the consultation)
`patientLastName`	No	Patient's last name

Example request

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

Response

A successful response returns the created invitation:

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

Field	Description
`encounterCompletionLinkText`	Text label for a hyperlink shown to the patient after completing the consultation
`encounterCompletionLinkUrl`	URL for a hyperlink shown to the patient after completing the consultation
`encounterId`	Initially `null`, populated once the patient starts the consultation
`id`	Unique identifier for the invitation
`invitationUrl`	The shareable link to send to the patient

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

The patient is shown a thank-you screen. If encounterCompletionLinkUrl was provided, a hyperlink will be shown as well.

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, but existing encounters are preserved. Existing invitation URLs will no longer work. See Deletion and cascading behavior for details.

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/consult-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/consult-invitation/<INVITATION_ID> \
  -H "Authorization: Bearer <ID_TOKEN>"

Authentication

Getting access