Quickstart

This guide takes you through one full request-response cycle against the Orizn API. By the end you'll have an API key, a working example in your language of choice, and a clear sense of what the response schema looks like.

You'll need: a free Orizn account, a terminal (or your language runtime), and roughly five minutes.

1. Get an API key

API keys live in your dashboard. The free tier ships with a generous 10 000 lookups / month, which is plenty for prototyping and small production apps.

1. Sign in to the dashboard.
2. Open the API keys tab and click Create key.
3. Copy the key (it starts with orizn_live_) and store it as an environment variable. Never commit it to source control.

export ORIZN_API_KEY="orizn_live_…"

2. Make your first request

The lookup endpoint takes two query parameters: passport and destination, both as ISO-3166 alpha-3 country codes. Pick the language you're building in:

curl https://api.orizn.app/visa \
  -H "Authorization: Bearer $ORIZN_API_KEY" \
  -G \
  --data-urlencode "passport=FRA" \
  --data-urlencode "destination=JPN"

import { Orizn } from "@orizn/sdk";

const client = new Orizn({ apiKey: process.env.ORIZN_API_KEY });

const result = await client.visa.lookup({
  passport: "FRA",
  destination: "JPN",
});

console.log(result.requirement);
// => "visa_free"

from orizn import Orizn

client = Orizn(api_key=os.environ["ORIZN_API_KEY"])

result = client.visa.lookup(
    passport="FRA",
    destination="JPN",
)

print(result.requirement)
# => "visa_free"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/orizn-app/orizn-go"
)

func main() {
  client := orizn.New(os.Getenv("ORIZN_API_KEY"))

  result, err := client.Visa.Lookup(context.Background(), orizn.VisaLookupParams{
    Passport:    "FRA",
    Destination: "JPN",
  })
  if err != nil {
    panic(err)
  }
  fmt.Println(result.Requirement) // visa_free
}

All four examples make the same call: “What does a French passport need to enter Japan?” — and all four return the same JSON payload.

3. Read the response

A successful lookup returns HTTP 200 with a JSON body that always includes requirement, stay_days, a human-readable notes field, and one or more authoritative sources:

{
  "passport": "FRA",
  "destination": "JPN",
  "requirement": "visa_free",
  "stay_days": 90,
  "notes": "France passport holders may enter Japan visa-free for tourism up to 90 days.",
  "updated_at": "2026-04-12T08:24:00Z",
  "sources": [
    { "name": "MOFA Japan", "url": "https://www.mofa.go.jp/j_info/visit/visa/short/novisa.html" }
  ]
}

The requirementfield is the one most integrations branch on. It's one of: visa_free, visa_on_arrival, e_visa, e_ta, visa_required, or not_admitted. See the API reference for the full schema, including optional fields like fee_usd and processing_days.

4. Handle errors

Non-2xx responses always include a structured error body so you can surface a useful message to the user or to your logs:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_passport",
    "message": "Unknown passport code: 'FR'. Did you mean 'FRA'?",
    "param": "passport"
  }
}

See the errors reference for the full status-code matrix and recommended handling.

Authentication

Every request must include an Authorization header in the form Bearer <key>. Keys come in two flavours:

• orizn_live_… — production keys, count against your billing quota, return real data.
• orizn_test_… — sandbox keys, free, always return a synthetic but schema-valid response.

Important: API keys are equivalent to passwords. Treat them as secrets — load from env vars or a vault, rotate regularly, and revoke immediately if a key leaks (the dashboard has a one-click revoke).

Next steps

• Drill into the full API reference.
• Subscribe to policy-change webhooks.
• Install an official SDK instead of hand-rolling HTTP calls.