Consultation Lifecycle

A consultation in DELPHOS follows a well-defined lifecycle. This guide walks through every stage — from opening a session to receiving the completed SOAP note.

Consultation Phases

The consultation phase tracks the clinical encounter flow.

ABERTO → ATENDIMENTO → GRAVACAO → FINALIZADO
  │          │    ↑        │
  │          │    └────────┘   (stop/start recording)
  │          │
  │          └─────────────→ FINALIZADO
  │
  └────────────────────────→ (timeout)

Phase	Description
`ABERTO`	Session created, waiting for physician to begin
`ATENDIMENTO`	Physician has started the clinical encounter
`GRAVACAO`	Audio recording is active
`FINALIZADO`	Consultation complete — SOAP note generated

Starting a Consultation

There are two ways to begin: streaming (with real-time audio) or text (with a pre-existing transcript).

curl -X POST "https://your-instance.delphos.app/v1/consultation/start" \
  -H "x-api-key: $DELPHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_consultation_id": "ATD-2024-001234",
    "external_patient_id": "PAT-5678",
    "language": "pt",
    "diarize": true,
    "metadata": {
      "doctor_id": "DOC-123",
      "specialty": "cardiology",
      "location": "clinic-a",
      "encounter_type": "follow-up"
    }
  }'

import httpx

response = httpx.post(
    "https://your-instance.delphos.app/v1/consultation/start",
    headers={"x-api-key": DELPHOS_API_KEY},
    json={
        "external_consultation_id": "ATD-2024-001234",
        "external_patient_id": "PAT-5678",
        "language": "pt",
        "diarize": True,
        "metadata": {
            "doctor_id": "DOC-123",
            "specialty": "cardiology",
            "location": "clinic-a",
            "encounter_type": "follow-up",
        },
    },
)

session = response.json()
session_id = session["session_id"]
print(f"Session started: {session_id}")

Response (201 Created):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_consultation_id": "ATD-2024-001234",
  "state": "ACTIVE",
  "created_at": "2026-04-14T10:30:00Z",
  "message": "Session created successfully. Ready to receive audio chunks."
}

Request Parameters

Field	Type	Required	Description
`external_consultation_id`	`string`	Yes	Your system’s consultation ID (1-255 chars)
`external_patient_id`	`string`	Yes	Your system’s patient ID
`language`	`string`	No	Transcription language (default: `pt`)
`diarize`	`boolean`	No	Enable speaker diarization (default: `true`)
`metadata.doctor_id`	`string`	Yes	Doctor’s external ID — must exist in DELPHOS
`metadata.specialty`	`string`	No	Medical specialty for context

Text Consultation

If you already have a transcript (e.g., from typed notes), skip audio and send the text directly:

curl -X POST "https://your-instance.delphos.app/v1/consultation/text" \
  -H "x-api-key: $DELPHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_consultation_id": "ATD-2024-001235",
    "external_patient_id": "PAT-5678",
    "transcript": "Doctor: Good morning. How are you feeling today?\nPatient: The headaches are less frequent now...",
    "metadata": {
      "doctor_id": "DOC-123",
      "specialty": "neurology"
    },
    "include_soap": true,
    "wait_for_soap": true
  }'

When wait_for_soap is true, the response waits for SOAP generation and returns 200 OK with the complete result. Set it to false to receive 202 Accepted and poll for the result.

Lifecycle Transitions

After creating a session, move it through phases to track the consultation progress:

Start Attendance

Signal that the physician has begun the encounter:

curl -X POST "https://your-instance.delphos.app/v1/consultation/{session_id}/start-attendance" \
  -H "x-api-key: $DELPHOS_API_KEY"

Transitions: ABERTO → ATENDIMENTO

Start Recording (optional)

Activate audio recording:

curl -X POST "https://your-instance.delphos.app/v1/consultation/{session_id}/start-recording" \
  -H "x-api-key: $DELPHOS_API_KEY"

Transitions: ATENDIMENTO → GRAVACAO

Stop Recording (optional)

Pause audio capture without ending the consultation:

curl -X POST "https://your-instance.delphos.app/v1/consultation/{session_id}/stop-recording" \
  -H "x-api-key: $DELPHOS_API_KEY"

Transitions: GRAVACAO → ATENDIMENTO

Finalize

End the consultation and trigger SOAP generation:

curl -X POST "https://your-instance.delphos.app/v1/consultation/{session_id}/finalize" \
  -H "x-api-key: $DELPHOS_API_KEY"

Transitions: ATENDIMENTO or GRAVACAO → FINALIZADO

Phase History

Retrieve the full audit trail of phase transitions:

curl -X GET "https://your-instance.delphos.app/v1/consultation/{session_id}/history" \
  -H "x-api-key: $DELPHOS_API_KEY"

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_phase": "FINALIZADO",
  "transitions": [
    {
      "from_phase": "ABERTO",
      "to_phase": "ATENDIMENTO",
      "triggered_at": "2026-04-14T10:30:00Z",
      "triggered_by": "api-key-id"
    },
    {
      "from_phase": "ATENDIMENTO",
      "to_phase": "GRAVACAO",
      "triggered_at": "2026-04-14T10:31:00Z",
      "triggered_by": "api-key-id"
    },
    {
      "from_phase": "GRAVACAO",
      "to_phase": "FINALIZADO",
      "triggered_at": "2026-04-14T10:45:00Z",
      "triggered_by": "api-key-id"
    }
  ]
}

Ending a Consultation

There are two endpoint forms for ending a consultation — both return the same response:

POST /v1/consultation/end — session_id provided in the request body
POST /v1/consultation/end/{session_id} — session_id in the URL path (shown below); also accepts accumulated_text for injecting physician notes

When ending a streaming consultation, you can include the physician’s accumulated notes and control SOAP generation:

curl
Python

curl -X POST "https://your-instance.delphos.app/v1/consultation/end/{session_id}" \
  -H "x-api-key: $DELPHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accumulated_text": "Paciente com cefaleia tensional há 3 dias. Prescrever analgesico.",
    "include_soap": true,
    "wait_for_soap": true
  }'

response = httpx.post(
    f"https://your-instance.delphos.app/v1/consultation/end/{session_id}",
    headers={"x-api-key": DELPHOS_API_KEY},
    json={
        "accumulated_text": "Paciente com cefaleia tensional há 3 dias.",
        "include_soap": True,
        "wait_for_soap": True,
    },
)

result = response.json()
print(f"SOAP subjective: {result['soap_note']['subjective'][:100]}...")

The accumulated_text field contains the physician’s typed notes, which are injected into the transcript before SOAP generation to enrich the clinical context.

Checking Session Status

Poll the status endpoint to track SOAP generation progress:

curl -X GET "https://your-instance.delphos.app/v1/consultation/{session_id}/status" \
  -H "x-api-key: $DELPHOS_API_KEY"

The response includes the session state, full transcript, statistics, and the SOAP note once generation completes.

Session States

The session state tracks audio streaming and SOAP generation progress — independent of the consultation phase above.

State	Description
`ACTIVE`	Receiving audio chunks
`PROCESSING_SOAP`	Audio complete, generating SOAP note
`COMPLETED`	SOAP generated successfully
`ERROR`	Processing error occurred
`TIMEOUT`	Session timed out (24h TTL)

Error Handling

Response Codes

Status	Meaning
`200 OK`	Request completed successfully
`201 Created`	Session created (streaming consultation)
`202 Accepted`	Request accepted, poll status endpoint for result (when `wait_for_soap=false`)

Error Details

Status	Cause
`409 Conflict`	Active session already exists for this consultation, or session not in valid state for the requested action
`422 Unprocessable Entity`	Missing required fields, or patient/doctor not found
`503 Service Unavailable`	Transcription or SOAP generation service temporarily unavailable

Next Steps

Real-time Transcription — Stream audio chunks
Working with Records — Edit and version finalized records
Clinical Summaries — Generate patient intelligence