Quickstart

Go from a fresh account to your first completed visa report in under five minutes. This walkthrough uses curl, but every step works the same way from any HTTP client or our official SDKs.

1. Confirm your environment

You need a recent curl (or any HTTP client), a HeyVisa account, and a terminal where you can set environment variables.

# Confirm your CLI environment
curl --version
# 8.x or higher recommended

2. Create an API key

Keys are created from the dashboard. Live keys are prefixed hv_live_ and test keys with hv_test_. Test keys do not consume credits and return deterministic sample reports.

# After signing in, navigate to:
#   Dashboard → Settings → API Keys → Create new key
# Then store it in your environment:

export HEYVISA_API_KEY="hv_live_xxxxxxxxxxxxxxxx"

3. Submit your first report

The minimum payload requires an applicant object with the issuing country, the destination, and the trip purpose. The response is returned immediately with status: "queued".

curl -X POST https://api.heyvisa.com/v1/reports \
  -H "Authorization: Bearer $HEYVISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant": {
      "country": "TR",
      "destination": "DE",
      "purpose": "tourism",
      "travel_dates": { "from": "2026-09-12", "to": "2026-09-22" }
    }
  }'

4. Poll for completion

Reports usually finish in 15 to 45 seconds. You can either poll the report endpoint or subscribe to the report.completed webhook (recommended for production).

curl https://api.heyvisa.com/v1/reports/rep_01HXYZ... \
  -H "Authorization: Bearer $HEYVISA_API_KEY"

5. Read the result

A completed report contains a numeric risk_score, a banded interpretation, and a list of prioritised recommendations.

{
  "id": "rep_01HXYZ...",
  "status": "completed",
  "risk_score": 72,
  "risk_band": "medium",
  "recommendations": [
    {
      "id": "rec_proof_of_funds",
      "priority": "high",
      "summary": "Add three months of bank statements."
    }
  ]
}

Common next steps

1. Wire up a webhook endpoint to avoid polling.
2. Upload supporting documents for richer risk signals.
3. Switch from test to live keys when you are ready.