> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt > Use this file to discover all available pages before exploring further. # List Documents > List stored documents, filtered by date, assignee, folder and more. Returns document metadata, newest first: documents synced from the EHR document inbox, documents recorded by a [patient](/api-reference/patients/fetch) or [appointment](/api-reference/appointments/fetch) live fetch, referral attachments and uploads. The file itself is not in the response; download it with [GET /documents/{id}](/api-reference/documents/get). When `has_file` is `false`, request it first with [POST /documents/fetch](/api-reference/documents/fetch). ## Query Parameters * **start\_date** (string, required): Start of the date range (YYYY-MM-DD). Matches the EHR scan date for inbox documents, otherwise the day Cobalt stored the document. * **end\_date** (string, required): End of the date range (YYYY-MM-DD, inclusive). * **inbox** (string, optional): `true` for only documents synced from the EHR document inbox, `false` to exclude them. * **assigned\_to\_ehr\_id** (string, optional): Assignee's staff `ehr_id` from [GET /staff](/api-reference/staff/get). * **assigned\_to\_name** (string, optional): Assignee name as shown in the EHR, e.g. `Smith,Jane`. Case- and space-insensitive. Use it for group assignees, which have no staff ID. * **folder\_ehr\_id** (string, optional): EHR folder (category) ID. * **folder\_name** (string, optional): Folder (category) name, case-insensitive. Inbox documents use the full folder path, e.g. `Fax Inbox/Referrals`. * **review\_required** (string, optional): `true` for documents marked for review in the EHR, `false` for the rest. * **patient\_mrn** (string, optional): Patient MRN. * **document\_type** (string, optional): `file` or `visit_note`. * **page** (integer, optional): Page number (default: 1). * **page\_size** (integer, optional): Results per page, max 100 (default: 100). ## Example Request ```bash theme={null} curl -G "https://api.usecobalt.com/v1/documents" \ -H "client_id: your_client_id" \ -H "client_secret: your_client_secret" \ -H "access_token: your_access_token" \ --data-urlencode "start_date=2026-10-05" \ --data-urlencode "end_date=2026-10-07" \ --data-urlencode "inbox=true" \ --data-urlencode "assigned_to_ehr_id=52685" \ --data-urlencode "review_required=true" ``` ## Example Response ```json theme={null} { "success": true, "documents": [ { "id": "3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12", "file_name": "50_1a289685-9bcd-4f28-a00c-139ba48d506d.pdf", "description": "Fax Inbox document", "mime_type": "application/pdf", "document_type": "file", "patient_mrn": null, "patient_ehr_id": null, "encounter_ehr_id": null, "folder_ehr_id": "137", "folder_name": "Fax Inbox", "assigned_to_ehr_id": "52685", "assigned_to_name": "Smith,Jane", "review_required": true, "is_high_priority": false, "tags": ["Referral"], "scanned_date": "2026-10-05", "service_date": null, "has_file": false, "created_at": "2026-10-05T14:02:11.000Z", "updated_at": "2026-10-05T14:02:11.000Z" } ], "pagination": { "page": 1, "page_size": 100, "total_count": 1, "total_pages": 1 } } ``` ## Staying Up To Date Subscribe to the `document.created` and `document.updated` [sync events](/docs/webhooks/sync-events#document-events) to hear about new inbox documents and changes (reassigned, refiled, marked for review) without polling. ## Status Codes * **200**: Documents returned. * **400**: Missing or invalid dates, an invalid filter value, or an invalid `page` / `page_size`. ## OpenAPI ````yaml GET /documents openapi: 3.1.0 info: title: Cobalt API version: 1.0.1 description: API for interacting with Cobalt's EHR integration services servers: - url: https://api.usecobalt.com/v1 description: Production security: - ClientCredentials: [] ClientSecret: [] AccessToken: [] paths: /documents: get: tags: - Documents summary: List documents description: >- Lists stored documents, newest first: the synced EHR document inbox, documents from patient and appointment live fetches, referral attachments and uploads. Metadata only; download a file with GET /v1/documents/{id}. operationId: getDocuments parameters: - name: start_date in: query description: >- Start of the date range (YYYY-MM-DD, inclusive). Matches the EHR scan date for inbox documents, otherwise the day Cobalt stored the document. schema: type: string example: '2026-03-15' required: true x-supported-emrs: - eClinicalWorks - Athena - Credible - Sunwave - name: end_date in: query description: End of the date range (YYYY-MM-DD, inclusive). schema: type: string example: '2026-03-20' required: true x-supported-emrs: - eClinicalWorks - Athena - Credible - Sunwave - name: patient_mrn in: query description: Filter by patient Medical Record Number. schema: type: string example: '12345' required: false x-supported-emrs: - eClinicalWorks - Athena - Credible - Sunwave - name: document_type in: query description: >- Filter by type: "file" (a stored file) or "visit_note" (an encounter visit note, rendered to PDF on fetch). schema: type: string enum: - file - visit_note required: false x-supported-emrs: - eClinicalWorks - Athena - Credible - Sunwave - name: inbox in: query description: >- "true" returns only documents synced from the EHR document inbox; "false" excludes them. schema: type: string enum: - 'true' - 'false' required: false x-supported-emrs: - eClinicalWorks - name: folder_ehr_id in: query description: Filter by EHR folder (category) ID. schema: type: string required: false x-supported-emrs: - eClinicalWorks - name: folder_name in: query description: >- Filter by folder (category) name, case-insensitive. Inbox documents use the full folder path, e.g. "Fax Inbox/Referrals". schema: type: string example: Lab Results required: false x-supported-emrs: - eClinicalWorks - Athena - Credible - Sunwave - name: assigned_to_ehr_id in: query description: 'Filter by assignee: a staff `ehr_id` from GET /v1/staff.' schema: type: string example: staff-123 required: false x-supported-emrs: - eClinicalWorks - Athena - Credible - Sunwave - name: assigned_to_name in: query description: >- Filter by assignee name as shown in the EHR (e.g. "Smith,Jane"), case- and space-insensitive. Use for group assignees, which have no staff ID. schema: type: string required: false x-supported-emrs: - eClinicalWorks - name: review_required in: query description: Filter by whether the document is marked for review. schema: type: string enum: - 'true' - 'false' required: false x-supported-emrs: - eClinicalWorks - name: page in: query description: Page number (default 1). schema: type: string example: '1' required: false x-supported-emrs: - eClinicalWorks - Athena - Credible - Sunwave - name: page_size in: query description: Results per page (1-100, default 100). schema: type: string example: '100' required: false x-supported-emrs: - eClinicalWorks - Athena - Credible - Sunwave responses: '200': description: Documents for the account content: application/json: schema: type: object properties: success: type: boolean documents: type: array items: type: object properties: id: type: string description: Cobalt document ID (dashless UUID). file_name: type: string description: type: - string - 'null' mime_type: type: string document_type: type: string enum: - file - visit_note description: >- "file" (a stored file) or "visit_note" (an encounter visit note, rendered to PDF on fetch). patient_mrn: type: - string - 'null' patient_ehr_id: type: - string - 'null' encounter_ehr_id: type: - string - 'null' folder_ehr_id: type: - string - 'null' folder_name: type: - string - 'null' assigned_to_ehr_id: type: - string - 'null' description: >- Assignee staff `ehr_id` (GET /v1/staff). Null for group assignees. assigned_to_name: type: - string - 'null' review_required: type: boolean description: >- Whether the document is marked for review in the EHR. is_high_priority: type: boolean tags: type: array items: type: string scanned_date: type: - string - 'null' description: >- Date the document entered the EHR inbox (YYYY-MM-DD). service_date: type: - string - 'null' has_file: type: boolean description: >- Whether the file is stored. When false, request it with POST /v1/documents/fetch before GET /v1/documents/{id}. created_at: type: string updated_at: type: string required: - id - file_name - description - mime_type - document_type - patient_mrn - patient_ehr_id - encounter_ehr_id - folder_ehr_id - folder_name - assigned_to_ehr_id - assigned_to_name - review_required - is_high_priority - tags - scanned_date - service_date - has_file - created_at - updated_at pagination: type: object properties: page: type: integer page_size: type: integer total_count: type: integer total_pages: type: integer required: - page - page_size - total_count - total_pages required: - success - documents - pagination '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' components: responses: BadRequest: description: Bad request — missing or invalid parameters content: application/json: schema: type: object properties: success: type: boolean enum: - false message: type: string required: - success - message Unauthorized: description: Unauthorized — missing or invalid credentials content: application/json: schema: type: object properties: success: type: boolean enum: - false message: type: string required: - success - message InternalServerError: description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false message: type: string required: - success - message securitySchemes: ClientCredentials: type: apiKey in: header name: client_id ClientSecret: type: apiKey in: header name: client_secret AccessToken: type: apiKey in: header name: access_token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.