Documents API

Documents are uploaded once and then referenced by ID from one or more reports. This avoids re-uploading the same passport scan across multiple analyses.

Upload a document

POST/v1/documents

Multipart upload. Returns immediately with status: "queued"; analysis runs asynchronously.

Form fields

Field	Type	Required	Description
file	binary	yes	PDF / JPG / PNG / HEIC. Max 20 MB for PDF, 10 MB for images.
type	string	no	Hint such as passport · bank_statement · employment_letter. Auto-detected if omitted.
filename	string	no	Override the original filename in the dashboard.

Request

bash

curl -X POST https://api.heyvisa.com/v1/documents \
  -H "Authorization: Bearer $HEYVISA_API_KEY" \
  -F "type=passport" \
  -F "file=@./passport.pdf"

Response

json

201 Created
{
  "id": "doc_01HXYZpassport",
  "object": "document",
  "type": "passport",
  "status": "queued",
  "size_bytes": 481203,
  "created_at": "2026-06-11T09:21:00Z"
}

Retrieve a document

GET/v1/documents/{id}

Returns the analysis result once status is analysed.

Response

json

200 OK
{
  "id": "doc_01HXYZpassport",
  "object": "document",
  "type": "passport",
  "status": "analysed",
  "extracted": {
    "passport_number": "U12345678",
    "expires_at": "2032-03-03"
  },
  "checks": [
    { "id": "expiry_buffer", "status": "pass" }
  ]
}

Delete a document

DELETE/v1/documents/{id}

Permanently removes the underlying file and all extracted data. Any reports that reference the document are not deleted, but their attached extraction will be marked as unavailable.

http

DELETE /v1/documents/doc_01HXYZpassport

204 No Content

Hard delete

Document deletion is immediate and irreversible. We do not keep soft-deleted copies. If you need an audit trail, export from the dashboard before deleting.