> ## 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.

# Fetch Document

> Fetch a document's file from the EMR.

Queues an on-demand fetch of a document's file from the EMR. This is asynchronous:
the endpoint returns a `job_id`, Cobalt retrieves the file from the EMR and stores
it, then sends a `document.live_fetch_completed` webhook. Retrieve the file with
[GET /documents/{id}](/api-reference/documents/get).

## Getting a `document_id`

Use the `document_id` returned by Cobalt for an EMR document, for example on the
chart documents in a [patient live fetch](/api-reference/patients/fetch)
response. Supported sources vary by EMR.

## Flow

1. `POST /documents/fetch` with a `document_id` returns `202` and a `job_id`.
2. Cobalt fetches the file from the EMR and stores it.
3. A `document.live_fetch_completed` webhook is sent with the document reference.
4. `GET /documents/{id}` returns the file.

## Example Request

```bash theme={null}
curl -X POST "https://api.usecobalt.com/v1/documents/fetch" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "your_document_id"}'
```

## Status Codes

* **202**: Fetch accepted; the document is delivered via webhook and retrievable at `GET /documents/{id}`.
* **400**: Missing or invalid `document_id`, or the connected EMR is not supported.


## OpenAPI

````yaml POST /documents/fetch
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/fetch:
    post:
      tags:
        - Documents
      summary: Fetch a document
      description: >-
        Queues a live fetch of a document's file from the EMR and stores it; the
        result is delivered by webhook and retrievable via GET
        /v1/documents/{id}.
      operationId: liveFetchDocument
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - document_id
              properties:
                document_id:
                  type: string
                  x-supported-emrs:
                    - Sunwave
                  description: >-
                    Cobalt document id identifying the EMR document to fetch
                    (e.g. from the patient live-fetch response).
                  example: swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9
                  x-required-for-emrs:
                    - Sunwave
                callback_urls:
                  type: array
                  items:
                    type: string
                  x-supported-emrs:
                    - Sunwave
                  description: >-
                    URLs to receive the completion webhook for this fetch, in
                    addition to the account webhook.
                  example:
                    - https://example.com/webhooks/cobalt
      responses:
        '202':
          description: Document fetch accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  job_id:
                    anyOf:
                      - type: string
                      - type: number
                required:
                  - success
                  - message
                  - job_id
        '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

````