Overview

AI Outputs are delivered in Particle's FLAT format as part of the patient dataset. When you query patient data, AI-generated summaries are included in the AI_Outputs table.

FLAT Schema: AI_Outputs

FLAT Schema: AI_Citations

AI Citations provide source attribution for AI-generated summaries. Each citation links specific statements in the AI output to the underlying clinical data, enabling source verification and transparency.

Retrieving AI Outputs

API Endpoint

GET /v2/patients/{particle_patient_id}/flat

You can filter to retrieve only AI Outputs:

GET /v2/patients/{particle_patient_id}/flat?AI_OUTPUTS

Or retrieve both AI Outputs and Citations:

GET /v2/patients/{particle_patient_id}/flat?AI_OUTPUTS&AI_CITATIONS

Example Request

curl -X GET "https://api.particlehealth.com/v2/patients/d939196d-0c80-4e82-b0e1-19f9ee271085/flat?AI_OUTPUTS&AI_CITATIONS" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "ai_outputs": [
    {
      "patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
      "ai_output_id": "ai_output_12345",
      "type": "PATIENT_HISTORY",
      "text": "Patient has a history of type 2 diabetes mellitus diagnosed in 2018, currently managed with metformin. Recent lab work shows HbA1c of 7.2%. No diabetic complications noted...",
      "resource_reference_ids": null
    }
  ],
  "ai_citations": [
    {
      "ai_output_id": "ai_output_12345",
      "citation_id": "citation_001",
      "particle_patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
      "resource_reference_id": "hash_abc123def456",
      "resource_type": "Problems",
      "text_snippet": "Type 2 diabetes mellitus without complications, diagnosed 03/2018."
    },
    {
      "ai_output_id": "ai_output_12345",
      "citation_id": "citation_002",
      "particle_patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
      "resource_reference_id": "hash_def456ghi789",
      "resource_type": "Medications",
      "text_snippet": "Metformin 1000mg tablet, take 1 tablet by mouth twice daily."
    },
    {
      "ai_output_id": "ai_output_12345",
      "citation_id": "citation_003",
      "particle_patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
      "resource_reference_id": "hash_ghi789jkl012",
      "resource_type": "Labs",
      "text_snippet": "Hemoglobin A1c: 7.2% (Reference range: <5.7%)"
    }
  ]
}

AI Output Types

PATIENT_HISTORY

Comprehensive overview of the patient's entire clinical history including demographics, chronic conditions, procedures, medications, lab trends, and key health events.

Use cases: New patient onboarding, annual wellness visits, chronic care management, comprehensive care planning

DISCHARGE_SUMMARY

Focused summary of a specific hospitalization including admission details, hospital course, procedures, discharge diagnoses, medications, and follow-up recommendations.

Use cases: Post-discharge care coordination, readmission prevention, care transitions, PCP notifications

Note: Discharge summaries are only available to Particle Signal customers. Signal monitors patients for new encounters and clinical events, automatically generating a discharge summary each time a discharge transition event is detected.

💡

More AI Output Types Coming Soon

Particle is expanding our library of AI-generated clinical summaries. Contact your Particle Solutions team to learn more about upcoming output types and discuss custom use cases for your organization.

Using AI Outputs and Citations Together

The AI_Outputs and AI_Citations tables work together to provide AI-generated summaries with full source transparency. Here's how to use them effectively:

Relationship Between Tables

The two tables are linked via the ai_output_id field:

• AI_Outputs table: Contains the AI-generated summary text
• AI_Citations table: Contains source attributions for statements in the summary

Each AI Output can have multiple citations, enabling you to trace any statement back to its source clinical documents.

Joining the Tables

To associate citations with their AI output:

-- Get an AI output with all its citations
SELECT
    ao.ai_output_id,
    ao.type,
    ao.text,
    COUNT(ac.citation_id) AS citation_count
FROM AI_Outputs ao
LEFT JOIN AI_Citations ac ON ao.ai_output_id = ac.ai_output_id
WHERE ao.ai_output_id = 'ai_output_12345'
GROUP BY ao.ai_output_id, ao.type, ao.text;

Retrieving Source Documents

Each citation includes a resource_reference_id (hash reference) and resource_type that point to the underlying FLAT resource. To retrieve the full source data, join to the corresponding FLAT table:

-- Example: Join citations to the Problems table
SELECT
    ac.citation_id,
    ac.text_snippet,
    p.*
FROM AI_Citations ac
JOIN Problems p ON ac.resource_reference_id = p.resource_reference_id
WHERE ac.ai_output_id = 'ai_output_12345'
    AND ac.resource_type = 'Problems';

-- Example: Get all source data for an AI output across multiple resource types
SELECT
    ac.citation_id,
    ac.resource_type,
    ac.text_snippet,
    CASE
        WHEN ac.resource_type = 'Problems' THEN p.code_display
        WHEN ac.resource_type = 'Medications' THEN m.medication_name
        WHEN ac.resource_type = 'Labs' THEN l.observation_name
    END AS source_description
FROM AI_Citations ac
LEFT JOIN Problems p ON ac.resource_type = 'Problems' AND ac.resource_reference_id = p.resource_reference_id
LEFT JOIN Medications m ON ac.resource_type = 'Medications' AND ac.resource_reference_id = m.resource_reference_id
LEFT JOIN Labs l ON ac.resource_type = 'Labs' AND ac.resource_reference_id = l.resource_reference_id
WHERE ac.ai_output_id = 'ai_output_12345';

Analyzing Citation Distribution

View which resource types support an AI output:

-- Count citations by resource type
SELECT
    resource_type,
    COUNT(*) AS citation_count
FROM AI_Citations
WHERE ai_output_id = 'ai_output_12345'
GROUP BY resource_type
ORDER BY citation_count DESC;

Use Cases

1. Source Verification Enable clinicians to click on statements in the AI summary and view the original clinical documents that support those statements.

2. Citation Display Show inline citations in your UI (e.g., superscript numbers) that link to detailed source information.

3. Resource Type Filtering Filter citations by resource_type to show which types of clinical data (Labs, Medications, Problems, etc.) support specific AI-generated statements.

4. Audit Trail Maintain a complete audit trail showing which source documents contributed to each AI-generated summary.

Webhook Notifications

Overview

Particle sends webhook notifications when AI Outputs are ready for a patient. Instead of polling the API to check if summaries have been generated, you'll receive a proactive notification when new AI Outputs are available.

Registering for Webhooks

To receive AI Output notifications, contact your Particle Health representative to configure your webhook endpoint. Particle will register your callback URL and provide a signature key for verifying webhook authenticity.

For complete webhook setup instructions and signature verification details, see Webhook Event Notifications.

Webhook Payload

When AI Outputs are generated, Particle sends a webhook notification with the following structure:

Example Webhook Payload

{
  "specversion": "1.0",
  "id": "baa927f8-fc4e-498c-80ba-0592b712ee8a",
  "source": "api/notifications",
  "type": "com.particlehealth.api.v2.aioutput",
  "subject": "New AI Outputs (PATIENT_HISTORY, DISCHARGE_SUMMARY)",
  "datacontenttype": "application/json",
  "time": "2025-11-25T22:35:12.745001633Z",
  "data": {
    "output_types": [
      "PATIENT_HISTORY",
      "DISCHARGE_SUMMARY"
    ],
    "particle_patient_id": "626a50b5-ec72-4839-8277-a0161e0a3129",
    "query_id": "26f68b3b-6694-4f48-ab93-295ea9c18932",
    "subject": "New AI Outputs (PATIENT_HISTORY, DISCHARGE_SUMMARY)"
  }
}

Webhook Payload Fields

Output Type Values

• PATIENT_HISTORY - Longitudinal patient summary
• DISCHARGE_SUMMARY - Discharge summary

Handling Webhook Notifications

When you receive a webhook notification:

1. Verify the signature using the x-ph-signature-256 header (see Webhook Event Notifications)

2. Extract the patient ID from data.particle_patient_id

3. Retrieve AI Outputs using the FLAT API endpoint: GET /v2/patients/{particle_patient_id}/flat?AI_OUTPUTS

Testing

Test AI Outputs in Particle's Sandbox environment with synthetic patient data. Contact your implementation team for Sandbox credentials and test patient IDs.