heyvisa
Developers

HeyVisa API for
developers.

Generate visa reports, parse documents, and stream updates straight into your product. A clean REST surface, SDKs in your favorite languages, and webhooks for every event.

# Generate a report in one call
curl -X POST https://api.heyvisa.com/v1/reports \
  -H "Authorization: Bearer $HEYVISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "app_8f3k2",
    "destination": "DE",
    "visa_type": "schengen_short_stay",
    "purpose": "tourism"
  }'
Authentication

Authenticate with an API key

Every request is authenticated with a bearer token. Generate one from Settings → API keys in your dashboard. Keys are scoped to a single workspace and can be rotated at any time without downtime.

Authorization: Bearer hv_live_4f8a2b6c9d3e1a7f0c5b8d2e6a9f3c1b

# Or pass it in code:
const heyvisa = new HeyVisa({
  apiKey: process.env.HEYVISA_API_KEY,
});
Endpoints

REST API reference

POST/v1/reportsCreate a new visa report from an applicant profile.
GET/v1/reports/:idRetrieve a generated report with full risk breakdown.
GET/v1/reportsList reports for the authenticated workspace.
POST/v1/applicantsCreate or update an applicant profile.
POST/v1/documentsUpload a supporting document for parsing.
DELETE/v1/reports/:idPermanently delete a report and its sources.

Example response

{
  "id": "rep_2k9j4hf8",
  "applicant_id": "app_8f3k2",
  "destination": "DE",
  "status": "completed",
  "risk_score": 78,
  "score_band": "low_risk",
  "criteria": [
    { "key": "financial_coverage", "score": 84, "weight": 0.22 },
    { "key": "travel_history",     "score": 71, "weight": 0.18 },
    { "key": "purpose_alignment",  "score": 80, "weight": 0.20 }
  ],
  "recommendations": [
    "Add a recent bank statement covering the last 90 days.",
    "Attach an updated invitation letter with passport reference."
  ],
  "created_at": "2026-06-10T14:22:01Z"
}
Rate limits

By plan

Free10 req/min100 reports / mo
Pro120 req/min10,000 reports / mo
EnterpriseCustomCustom

Rate-limit headers (X-RateLimit-Remaining) are returned on every response.

Webhooks

Get notified the moment something happens

Subscribe a URL to events and receive signed JSON payloads. Every payload includes an X-HeyVisa-Signature header you can verify with your webhook secret.

report.createdFired when a new report is created via API or dashboard.
report.completedFired when the AI analysis has finished and the report is ready.
report.failedFired when a report could not be generated due to invalid input.
document.parsedFired when an uploaded document has been parsed and indexed.
POST https://your-app.com/webhooks/heyvisa
X-HeyVisa-Signature: t=1718031721,v1=4f8a...

{
  "type": "report.completed",
  "data": {
    "report_id": "rep_2k9j4hf8",
    "risk_score": 78
  }
}