Global Clinic ConnectGuides
Integration step 05

Ingest documents

Create a document and upload its bytes through a short-lived, controlled upload form.

OutcomeA partner upload that enters the normal document preparation flow
Required scopesdocuments:write
Step by step

Typical integration workflow

01

Inspect the file

Know the exact name, MIME type, and byte size before asking for an upload form.

02

Create the document

Send the metadata to the ingestion endpoint and record document_id and version_id.

03

Upload with the returned form

Create a multipart form using every returned field unchanged, add the file, and POST it to upload.url before it expires.

04

Wait for preparation

The document begins security checks and preview preparation after upload. There is no separate confirmation request.

05

Handle rejected files

Do not retry blocked types unchanged. For size or usage limits, follow the returned guidance or contact the workspace administrator.

API reference

Endpoint for this capability

These are the supported public contracts for this integration step.

POST/api/ingest/documents
Scope · documents:write

Start a document upload

Create a document record and receive a short-lived upload form for server-side or partner ingestion.

Example request
POST /api/ingest/documents
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "sample-referral.pdf",
  "mime": "application/pdf",
  "size": 82311,
  "title": "Sample referral",
  "category": "referral",
  "tags": ["partner-import"]
}
Example response
{
  "document_id": "doc_example",
  "version_id": "version_example",
  "status": "pending_scan",
  "upload": {
    "url": "https://temporary-upload.example.invalid/",
    "fields": { "key": "temporary-value" }
  },
  "expires_in": 300,
  "max_bytes": 104857600
}

Error handling

400validation error

Provide name, MIME type, and byte size.

403INSUFFICIENT_SCOPE

Create a key with documents:write.

409FILE_TYPE_NOT_ALLOWED

Use a supported file type.

409FILE_TOO_LARGE

Keep the file below max_bytes.

409USAGE_LIMIT_EXCEEDED

Review the workspace’s upload or storage allowance.

Best practices

  • Send the exact file size before requesting the upload.
  • Upload immediately because the form expires.
  • Submit the returned fields unchanged with the file.
  • Do not call a separate confirmation endpoint; processing begins after upload.
Try this endpoint in the console
Production checklist

Best practices

  • ✓Upload immediately after creating the document.
  • ✓Never log the returned upload fields.
  • ✓Use accurate file metadata.
  • ✓Do not reuse an upload form for another file.
Interactive console

Try a supported API

Requests go directly from this browser tab to the API environment you choose. Keys and responses are held in memory only and are cleared when the page closes.

Do not use real patient data in tests
POST/api/ingest/documents
Response
Ready when you are

Enter a test key, review the sample request, and send it. The response will appear here.

Equivalent cURL example
curl -X POST 'https://api.connect.globalclinic.app/api/ingest/documents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{
  "name": "sample-referral.pdf",
  "mime": "application/pdf",
  "size": 82311,
  "title": "Sample referral",
  "category": "referral",
  "tags": ["partner-import"]
}'
Required scopedocuments:write

Create a document record and receive a short-lived upload form for server-side or partner ingestion.

Next steps