HelloGov + iVisa have merged to create the world's largest passport and visa company. Read more →

hellogov
Start Application
GovSchema

The open standard for agent-driven government services

Machine-readable JSON schemas for passports, visas, and citizen services. MIT licensed. Updated daily. Built for AI agents.

Start BuildingView on GitHub
govschema hero meta
4,000+Visa lanes
15,000+Configurations
DailyUpdates
govschema hero background
LIVE SCHEMAS

Explore the schema standard

Real GovSchema JSON files from the open-source repository. Every schema defines eligibility rules, form fields, fees, processing times, and required documents.

VISA/LANES/US-BR.JSON
import Ajv from "ajv";
import addFormats from "ajv-formats";

// 1. Fetch the schema
const schema = await fetch(
  "https://govschema.org/schema/visa/lanes/US-BR.json"
).then((r) => r.json);

// 2. Compile validator
const ajv = new Ajv({ allErrors: true, strict: true });
addFormats(ajv);
const validate = ajv.compile(schema);

// 3. Validate agent output
const draft = await agent.invoke({
  input: "Prepare a Brazil tourist visa application",
  responseSchema: schema,
});

if (!validate(draft)) {
  // Handle remediation
  console.log(validate.errors);
}
AI agent passport banner
For AI Agent Builders Integrate in five minutes

Fetch a schema, validate a payload, submit an application. Everything your agent needs to handle government services without scraping or parsing human-readable pages.

Start an application
Quickstart

From zero to production in five steps

Each checkpoint builds on the last. Skip ahead if your stack already handles a step.

Get your API key

Sign up at govschema.org, create a project, and generate sandbox + production keys. Scope keys per service for least-privilege access.

1/5
API REFERENCE

Endpoints by domain

All endpoints return JSON. Path parameters in curly braces should be replaced with values. Authentication required for production.

Passport2 endpoints
GET

/api/v1/passport/requirements/{country}

Eligibility rules, fees, documents, processing times.

GET

/api/v1/passport/status/{submissionId}

Real-time application status polling.

Visa2 endpoints
GET

/api/v1/visa/requirements/{origin}/{destination}

Visa requirements for a travel lane.

GET

/api/v1/visa/lanes/{origin}-{destination}

Full lane configuration with eligibility matrix.

Processing3 endpoints
GET

/api/v1/processing-times/{service}

Real-time processing time estimates.

GET

/api/v1/fees/{service}/{type}

Fee schedules by service and type.

GET

/api/v1/documents/{service}/{type}

Required document specifications.

Authentication
Headers and request identity

Standardize headers across all clients so retries, audits, and incident triage are predictable.

Authorization

Bearer <API_KEY>
Project-scoped key. Rotate every 90 days.

X-HelloGov-Env

sandbox | production
Controls data source and validation.

Idempotency-Key

UUID v4
Prevents duplicate writes on retries.

X-Correlation-ID

trace ID
Required for support triage and audit trails.

popular destinations background
ERROR HANDLING

Error catalog and remediation

Map API failures to deterministic agent behavior and user-facing next steps.

Client Errors1 code · 4xx/5xx
400INVALID_INPUT

Payload fails schema validation.

Map field errors to user remediation and retry.

401UNAUTHORIZED

API key missing, expired, or wrong env.

Refresh credentials, verify env routing, retry once.

409CONFLICT

Idempotency key reused with mismatched payload.

Surface policy reason, guide to eligible alternative.

422POLICY_BLOCK

Request violates lane-specific policy.

Generate new key or reuse original payload exactly.

Server Errors1 code · 4xx/5xx
429RATE_LIMITED

Throughput quota exceeded.

Exponential backoff, queue non-urgent requests.

503UNAVAILABLE

Maintenance or upstream outage.

Fail over to cached read model, retry after window.

All errors include a stable error_code and human-readable remediation field — safe to surface directly to end users.

SDKS AND TOOL DEFINITIONS

Drop-in integration for every stack

Copy-paste examples for the most popular AI agent frameworks. All examples use the GovSchema API at govschema.org.

VALIDATION_AGENT.JS
import Ajv from "ajv";
import addFormats from "ajv-formats"

// 1. Fetch the schema
const schema = await fetch(
  "https://govschema.org/schema/visa/lanes/US-BR.json"
).then((r) => r.json

// 2. Compile validator
const ajv = new Ajv({ allErrors: true, strict: true });
addFormats(ajv);
const validate = ajv.compile
WEBHOOKS

Event contracts for operational automation

Signed webhook events keep partner systems, support tooling, and analytics pipelines synchronized.

  • application.submitted

    Payload submissionId, lane, schemaVersion, createdAt Primary Use Trigger support timeline and customer confirmation.

  • validation.failed

    Payload submissionId, errors[], remediationHints[] Primary Use Route to correction flow before human review.

  • status.updated

    Payload submissionId, previousStatus, currentStatus, eta Primary Use Sync customer updates in CRM and partner channels.

  • policy.changed

    Payload lane, effectiveAt, changeType, impactedFields[] Primary Use Invalidate stale cache and notify policy ops.

  • submission.completed

    Payload submissionId, completedAt, outcome Primary Use Close operational loop and publish analytics.

webhook events background
INTEGRATION

SLO targets and resilience model

Default resilience posture for production agents and enterprise workloads.

99.9%

API availability

Monthly, across read and validation endpoints.

< 450ms

P95 latency

Cached requirements and schema fetch.

< 60s

Webhook delivery

At-least-once with replay support.

< 15 min

Schema propagation

Policy publication to API edge cache.

Retry policy

resilience

Retry 5×x with exponential backoff

250ms → 4s, full jitter

Never retry 4×x

Until payload is corrected by the client

Idempotency keys

Required on all write operations

Dead-letter queue

For max-attempt breaches and triage

Rate-limit guidance

throughput

Batch non-urgent reads

Where possible, to smooth burst load

Cache stable schema metadata

Aggressively at the edge

Prioritize user-facing validation calls

Over background reconciliation

Queue burst traffic

Drain by priority tier and SLA class

AI agent passport banner
The case for standardization

AI agents will interact with government systems on behalf of citizens at scale. Without a standard protocol, every agent builds its own automations — creating unpredictable load, inconsistent data handling, and security risk. GovSchema provides the common language.

Start an application
Convenient passport photo services at cvs locations nationwide
ARCHITECTURE

Three-tier model

From open-source adoption to government middleware. Each tier builds on the last.

Tier 1

Open-Source Standard

Public GitHub repo with daily-maintained JSON schemas. MIT licensed. Agent frameworks and LLMs absorb the standard.

  • Form fields, eligibility, validation rules
  • Document requirements and fee schedules
  • 15,000+ configurations maintained daily
  • The data can be forked — the maintenance cannot
Recommended

Commercial API

Real-time intelligence that static schemas cannot provide. Per-query and per-transaction pricing.

  • Processing-time predictions
  • Application status polling with push notifications
  • Collective intelligence from aggregated data
  • Managed end-to-end submission pipelines
Tier 3

B2G Middleware

Two-way sync between government systems and the agent ecosystem. Enterprise SaaS contracts.

  • Push notifications into government stack
  • Citizen demand analytics and forecasting
  • Pre-built bridge to the agent ecosystem
  • Compliance and audit layer
ADOPTION

Path for government agencies

A phased approach from evaluation to full deployment.

Read the full government framework

Evaluate the standard

Review the open-source schemas on GitHub. Assess alignment with your existing data structures and IT security requirements.

1/4
SCHEMA CATALOG
Open-source schema repositories

JSON schemas for government document requirements. MIT licensed, updated daily.

Visa Lanes

Origin-to-destination travel lanes with eligibility, fees, and document requirements

Passport

Country-specific passport services, renewal and first-time application schemas.

DMV

Leading in AI-powered government travel services. Optimizing every mission.

View on GitHub
popular destinations background
GOVERNANCE

Data governance and operational controls

Recommended controls for teams handling citizen data and regulated government workflows.

PII boundaries

Tokenize sensitive fields in logs and analytics. Isolate access by role and service context. Never persist raw PII in schema validation traces.

Audit traceability

Persist schema version, model ID, correlation ID, and user consent metadata per submission. Reconstruct any decision path on demand.

Policy drift management

Subscribe to policy changed events and invalidate outdated caches immediately. Enforce schema version pinning to prevent silent regressions.

Whitepaper
The infrastructure layer for agent-driven government services

Full thesis on why open schemas win, the three-tier monetization model, and the closing window to define the standard.

resources hero meta
Read the WhitepaperBook a Meeting
resources hero background
Get Started

Expedite your passport through
our AI-powered platform

Whether you need a passport, visa, or want to partner with us — HelloGov makes it simple.

Start Application
HelloGov application dashboard showing a passport renewal in progress