> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altohealth.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Document

> Upload a medical referral document for processing

## Overview

Upload a medical referral document along with associated metadata for processing. This endpoint accepts multipart form data with the document file and related information.

## Endpoint

```
POST https://app.arahealth.io/api/v1/pub/records/document-upload
```

**Base URL:** `https://app.arahealth.io`
**Path:** `/api/v1/pub/records/document-upload`
**Method:** `POST`

## Request Parameters

### Headers

* `Authorization` (required) - Bearer token for authentication (format: `Bearer ara_live_YOUR_API_KEY`)

### Form Data

* `referral` (required) - The referral document file (PDF, image, etc.)
* `referralSource` (optional) - Source of the referral

## Code Examples

<CodeGroup>
  ```csharp C# theme={null}
  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.Post, "https://app.arahealth.io/api/v1/pub/records/document-upload");
  request.Headers.Add("Authorization", "Bearer ara_live_YOUR_API_KEY");

  var content = new MultipartFormDataContent();
  content.Add(new StreamContent(File.OpenRead("/path/to/referral.pdf")), "referral", "referral.pdf");
  content.Add(new StringContent(""), "referralSource");

  request.Content = content;
  var response = await client.SendAsync(request);
  response.EnsureSuccessStatusCode();
  Console.WriteLine(await response.Content.ReadAsStringAsync());
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append('referral', fileInput.files[0]);
  formData.append('referralSource', '');

  const response = await fetch('https://app.arahealth.io/api/v1/pub/records/document-upload', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ara_live_YOUR_API_KEY'
    },
    body: formData
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.arahealth.io/api/v1/pub/records/document-upload"

  headers = {
      "Authorization": "Bearer ara_live_YOUR_API_KEY"
  }

  files = [
      ('referral', ('referral.pdf', open('/path/to/referral.pdf', 'rb'), 'application/pdf'))
  ]

  data = {
      "referralSource": ""
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl -X POST https://app.arahealth.io/api/v1/pub/records/document-upload \
    -H "Authorization: Bearer ara_live_YOUR_API_KEY" \
    -F "referral=@/path/to/referral.pdf" \
    -F "referralSource="
  ```
</CodeGroup>

## Response

A successful upload returns a JSON object with the following structure:

```json theme={null}
{
  "data": [
    {
      "name": "XXXXSyntheticReferral-Breast-T1-03-10-04-2025-NA-008.docx.pdf",
      "status": "complete",
      "record_id": "692b56267a5069e2517787e5"
    }
  ],
  "status_code": 200,
  "message": "success"
}
```

### Response Fields

* `data` - Array of uploaded document records
  * `name` - Filename of the uploaded document
  * `status` - Processing status (`complete`, `incomplete`)
  * `record_id` - Unique identifier for the uploaded record
* `status_code` - HTTP status code (200 for success)
* `message` - Status message


## OpenAPI

````yaml POST /api/v1/pub/records/document-upload
openapi: 3.1.0
info:
  title: Alto HealthAPI
  description: API for managing healthcare records and document uploads
  version: 1.0.0
servers:
  - url: https://app.arahealth.io
security:
  - bearerAuth: []
paths:
  /api/v1/pub/records/document-upload:
    post:
      summary: Upload Document
      description: Upload a medical referral document for processing
      requestBody:
        description: Multipart form data containing document and metadata
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DocumentUploadRequest'
      responses:
        '200':
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '400':
          description: Bad request - invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid API key or org_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadAuthError'
              example:
                message: Invalid API key
                detail: >-
                  connection(localhost:27017[-3]) incomplete read of message
                  header: read tcp [::1]:55900->[::1]:27017: use of closed
                  network connection
                status_code: 401
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DocumentUploadRequest:
      type: object
      required:
        - referral
      properties:
        referral:
          type: string
          format: binary
          description: The referral document file (PDF, image, etc.)
        referralSource:
          type: string
          description: Optional source of the referral
          example: ''
    DocumentUploadResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of uploaded document records
          items:
            $ref: '#/components/schemas/UploadedDocument'
        status_code:
          type: integer
          description: HTTP status code
          example: 200
        message:
          type: string
          description: Status message
          example: success
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code or type
        message:
          type: string
          description: Human-readable error message
    DocumentUploadAuthError:
      type: object
      required:
        - message
        - status_code
      properties:
        message:
          type: string
          description: Error description
          example: Invalid API key
        detail:
          type: string
          description: Detailed error information
          example: >-
            connection(localhost:27017[-3]) incomplete read of message header:
            read tcp [::1]:55900->[::1]:27017: use of closed network connection
        status_code:
          type: integer
          description: HTTP status code
          example: 401
    UploadedDocument:
      type: object
      properties:
        name:
          type: string
          description: Filename of the uploaded document
          example: SyntheticReferral-Breast-T1-01-10-04-2025-NA-009.pdf
        status:
          type: string
          description: Processing status of the document
          enum:
            - incomplete
            - processing
            - completed
            - failed
          example: complete
        record_id:
          type: string
          description: Unique identifier for the uploaded record
          example: example_record_id_123
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Bearer token authentication using your Alto Health API key

````