Reports API

Reports are the central object in HeyVisa. Each report ties an applicant profile to a set of documents and returns a risk-scored analysis with recommendations.

Create a report

POST/v1/reports

Submits a new analysis job. Returns immediately with status: "queued". Completion is delivered via webhook or by polling the GET endpoint.

Body parameters

Parameter	Type	Required	Description
applicant	object	yes	Applicant profile (see below).
documents	string[]	no	Array of document IDs to attach.
webhook_url	string	no	HTTPS URL to receive completion events.
metadata	object	no	Free-form key/value pairs (max 20 keys, 500 chars each).

Request

http

POST /v1/reports
{
  "applicant": {
    "country": "TR",
    "destination": "DE",
    "purpose": "tourism"
  },
  "documents": ["doc_01HXYZpassport"],
  "webhook_url": "https://app.example.com/heyvisa/hooks"
}

Response

json

201 Created
{
  "id": "rep_01HXYZ8K7M3N5P2Q4R6S8T0V2W",
  "object": "report",
  "status": "queued",
  "created_at": "2026-06-11T09:21:14Z"
}

Retrieve a report

GET/v1/reports/{id}

Returns the current state of a report, including completed analysis when ready.

Path parameters

Parameter	Type	Description
id	string	The report ID returned at creation.

Response

json

200 OK
{
  "id": "rep_01HXYZ8K7M3N5P2Q4R6S8T0V2W",
  "object": "report",
  "status": "completed",
  "risk_score": 72,
  "risk_band": "medium",
  "recommendations": [ ... ]
}

List reports

GET/v1/reports

Paginated list, newest first.

Query parameters

Parameter	Type	Default	Description
limit	integer	20	Page size, 1–100.
starting_after	string	—	Cursor: ID of the last item on the previous page.
status	enum	—	Filter by queued · processing · completed · failed.

Response

json

200 OK
{
  "object": "list",
  "has_more": true,
  "data": [
    { "id": "rep_01HXYZ...", "status": "completed", "risk_score": 72 },
    { "id": "rep_01HXAB...", "status": "queued",    "risk_score": null }
  ]
}