API reference — Orizn API | Orizn for Chrome

The Orizn API is intentionally small. There is one endpoint that answers the visa-requirement question; everything else (destinations, supported passports, policy history) is exposed as optional helpers most integrations never touch.

`GET` `https://api.orizn.app/visa`

Look up the visa requirement for a passport-destination pair. Idempotent, cacheable, free of side effects.

Parameters

Name	Type	Required	Description
`passport`	string	Yes	ISO-3166 alpha-3 code of the passport-holder's nationality. Example: `FRA`, `USA`, `VNM`.
`destination`	string	Yes	ISO-3166 alpha-3 code of the country the traveller wants to enter. Example: `JPN`.
`purpose`	enum	No	One of `tourism`, `business`, `transit`, `study`. Defaults to `tourism`. Other purposes may return different requirements (e.g. business visas).
`stay_days`	integer	No	Intended length of stay in days. Used to refine the answer for destinations where the requirement changes by duration (e.g. 90-day visa-free becomes visa-required for longer stays).
`locale`	string	No	BCP-47 tag for the `notes` field language. Defaults to `en`. Supported: `en`, `fr`, `es`, `de`, `ja`, plus 10 others — see the extension FAQ.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <api_key>` — see Authentication.
`Orizn-Version`	No	Pin a specific API version (e.g. `2026-04-01`). If absent, the version stored in your dashboard is used.
`Idempotency-Key`	No	Any client-generated UUID. The first response is cached and replayed for 24h. Useful behind unreliable network paths.
`Accept-Encoding`	No	We honour `gzip`, `br` and `zstd`. Brotli is recommended for browser clients.

Response schema

All successful responses are HTTP 200 and have the following shape:

Field	Type	Description
`passport`	string	Echoed from the request, normalised to upper-case alpha-3.
`destination`	string	Echoed from the request, normalised to upper-case alpha-3.
`requirement`	enum	One of `visa_free`, `visa_on_arrival`, `e_visa`, `e_ta`, `visa_required`, `not_admitted`. This is the field you branch on.
`stay_days`	integer \| null	Max allowed stay under the returned requirement. `null` when the rule is duration-agnostic.
`fee_usd`	number \| null	Official fee in USD where applicable (e-visa, VoA). Always`null` for visa-free.
`processing_days`	integer \| null	Typical processing time in business days.
`evisa_url`	string \| null	Direct link to the official e-visa application portal, when one exists.
`notes`	string	Short human-readable explanation, localised per the `locale` parameter.
`documents_required`	string[]	Slugged list of required documents, e.g. `passport`, `onward_ticket`, `proof_of_funds`.
`updated_at`	string (ISO-8601)	Timestamp of the last time this specific pair was reviewed.
`sources`	array	Citations to the official government source(s) backing the answer. Each object has `name` and `url`.
`trust`	object	Confidence metadata: `score`(0–1) and `last_verified_at` ISO timestamp. Surface this to end-users for transparency.

Example

Request:

bashlookup.sh

curl https://api.orizn.app/visa \
  -H "Authorization: Bearer $ORIZN_API_KEY" \
  -H "Orizn-Version: 2026-04-01" \
  -G \
  --data-urlencode "passport=FRA" \
  --data-urlencode "destination=JPN" \
  --data-urlencode "purpose=tourism"

Response:

json200.json

{
  "passport": "FRA",
  "destination": "JPN",
  "requirement": "visa_free",
  "stay_days": 90,
  "fee_usd": null,
  "processing_days": null,
  "evisa_url": null,
  "notes": "France passport holders may enter Japan visa-free for tourism up to 90 days. Passport must be valid for the duration of stay.",
  "documents_required": ["passport"],
  "updated_at": "2026-04-12T08:24:00Z",
  "sources": [
    { "name": "MOFA Japan", "url": "https://www.mofa.go.jp/j_info/visit/visa/short/novisa.html" }
  ],
  "trust": {
    "score": 0.98,
    "last_verified_at": "2026-05-20T11:02:00Z"
  }
}

Errors

Non-2xx responses always include a structured error body. See the full errors reference for the complete table. The most common ones for this endpoint:

Status	Code	Cause
400	`invalid_passport`	Unknown or malformed passport ISO code.
400	`invalid_destination`	Unknown or malformed destination ISO code.
401	`missing_api_key`	The `Authorization` header is absent or empty.
403	`quota_exceeded`	Your plan's monthly quota is used up.
429	`rate_limited`	You've exceeded the per-second burst allowance.

Rate limits

Rate limits protect the upstream government sources we cite. They are per-API-key and reset on a rolling window.

Free tier — 10 requests/second burst, 10 000 requests/month.
Pro tier — 100 requests/second burst, 1 000 000 requests/month.
Enterprise — custom; contact [email protected].

Every response includes the following headers so you can implement a polite client without guessing:

X-RateLimit-Limit— your current per-second cap.
X-RateLimit-Remaining— how many requests you can still make this second.
X-RateLimit-Reset— epoch seconds at which the bucket replenishes.
Retry-After— only on 429; seconds to wait before retrying.

Versioning

The API is versioned by date string, e.g. 2026-04-01. Pin a version by sending the Orizn-Version header on every request, or by setting a default version in the dashboard. Breaking changes ship as new versions; the previous version stays online for at least 12 months.

GET https://api.orizn.app/visa