Encounters

Create or update encounter records and manage documents via the Integration API.

Create or update encounter (patient visit) records and manage associated documents.

Upsert Encounter

POST /integration/encounters

Creates or updates an encounter by id. Referenced entities (patient_id, provider_id, rendering_provider_id, facility_id) must use the same id values you provided when creating those records via their respective endpoints.

Request Body

Field	Type	Required	Description
`id`	string	Yes	Your unique identifier for this encounter
`patient_id`	string	Yes	Patient ID (must exist)
`provider_id`	string	No	Billing/attending provider ID
`rendering_provider_id`	string	No	Rendering provider ID (if different)
`facility_id`	string	No	Facility ID where service was rendered
`date_of_service`	string (ISO 8601)	No	Date and time of service
`visit_type`	string	No	Type of visit (see values below)
`status`	string	No	Encounter status
`is_completed`	boolean	No	Whether the encounter is complete

Visit Types

Value	Description
`office_visit`	Standard office visit
`telehealth`	Virtual/telehealth visit
`inpatient`	Inpatient admission
`outpatient`	Outpatient procedure
`emergency`	Emergency department visit
`observation`	Observation stay
`surgical`	Surgical procedure

Example Request

curl -X POST https://api.neuralrev.ai/integration/encounters \
  -H "x-api-key: nrev_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ENC-001",
    "patient_id": "PAT-001",
    "provider_id": "PROV-001",
    "rendering_provider_id": "PROV-002",
    "facility_id": "FAC-001",
    "date_of_service": "2026-01-15T09:00:00Z",
    "visit_type": "office_visit",
    "status": "completed",
    "is_completed": true
  }'

Response

200 OK — Encounter upserted successfully:

{
  "success": true,
  "message": "Encounter upserted successfully"
}

400 Bad Request — Referenced entity not found:

{
  "error": "Patient not found for id: PAT-999"
}

Notes

Create patients, providers, and facilities before creating encounters that reference them.
If rendering_provider_id is not provided, the provider_id is assumed to be the rendering provider.
Setting is_completed: true marks the encounter as ready for billing workflow.

Upload Document

POST /integration/encounters/{id}/documents

Uploads a document to an encounter. If a document with the same document_id already exists, it is replaced.

Path Parameters

Parameter	Type	Description
`id`	string	Encounter ID

Request Body (multipart/form-data)

Field	Type	Required	Description
`file`	binary	Yes	The document file (PDF or DOCX)
`document_id`	string	Yes	Your unique identifier for this document
`category`	string	Yes	Document category (see values below)

Document Categories

Value	Description
`radiology_report`	Radiology/imaging reports
`lab_results`	Laboratory test results
`diagnostic_report`	Other diagnostic reports
`progress_report`	Clinical progress notes
`discharge_summary`	Hospital discharge summary
`doctor_notes`	Physician notes
`medical_record`	General medical records
`patient_history`	Patient history documents
`immunization_report`	Immunization records
`referral`	Referral letters
`consent_form`	Patient consent forms

Example Request

curl -X POST https://api.neuralrev.ai/integration/encounters/ENC-001/documents \
  -H "x-api-key: nrev_YOUR_API_KEY" \
  -F "file=@/path/to/clinical-notes.pdf" \
  -F "document_id=DOC-001" \
  -F "category=doctor_notes"

Response

200 OK — Document uploaded successfully:

{
  "success": true,
  "document_id": "DOC-001"
}

404 Not Found — Encounter not found:

{
  "error": "Encounter not found"
}

Constraints

Maximum file size: 250 MB
Supported formats: PDF (.pdf) and DOCX (.docx)
If you upload with an existing document_id, the previous file is replaced

Delete Document

DELETE /integration/encounters/{id}/documents/{documentId}

Deletes a document from an encounter.

Path Parameters

Parameter	Type	Description
`id`	string	Encounter ID
`documentId`	string	Document ID (the `document_id` used during upload)

Example Request

curl -X DELETE https://api.neuralrev.ai/integration/encounters/ENC-001/documents/DOC-001 \
  -H "x-api-key: nrev_YOUR_API_KEY"

Response

200 OK — Document deleted successfully:

{
  "success": true,
  "message": "Document deleted successfully"
}

404 Not Found — Document or encounter not found:

{
  "error": "Document not found"
}

Encounters

On this page