VisaPathways
Log inCreate free account

API v1

VisaPathways API documentation

Authenticate with an enterprise API key to read published route intelligence, evaluate compiled compliance rules, and retrieve persisted tenant-scoped audit records. Legal thresholds come from the Knowledge Ledger, not from client input.

Header: x-visapathways-enterprise-token. Send a provisioned key, never a user JWT, admin cookie, or service-role credential. Example value in this document is not a real key: vp_live_example_not_a_real_key. Developers can issue a short-lived vp_test_ sandbox key from /enterprise/sandbox.

Authentication

Production keys are shown once when provisioned and stored only as SHA-256 digests. Inactive keys, expired keys, and inactive tenants receive 401 INVALID_OR_EXPIRED_ENTERPRISE_TOKEN.

Migration Intelligence Data API

Normalized official destination statistics with immutable dataset versions, freshness, source-reported versus derived labels, and reproducible changed-since updates. It does not sell a raw World Bank payload or claim live migration.

  • GET /api/v1/intelligence/destinations?limit=25&offset=0
  • GET /api/v1/intelligence/destinations/{countryCode}
  • GET /api/v1/intelligence/destinations/{countryCode}/history
  • GET /api/v1/intelligence/versions
  • GET /api/v1/intelligence/changes?since=2026-01-01T00:00:00Z

Route Intelligence

Unpublished catalog routes are not exposed. Legal requirements come from published Knowledge Ledger records, not CMS eligibility notes.

  • GET /api/v1/routes/{slug}
  • GET /api/v1/routes/{slug}/sources
  • GET /api/v1/routes/{slug}/changes?since=2026-01-01&limit=50

GET rate limit: 60 requests per 60 seconds per production API key. Sandbox keys are limited more tightly. Exceeding the limit returns 429 RATE_LIMITED.

Evaluate a compliance rule

POST /api/v1/compliance/evaluate resolves the highest applicable rule version for the requested evaluation date. Current published versions and historically superseded versions remain date-addressable, so a historical evaluation reproduces the rule that applied at that time. Candidate fields are facts only; clients cannot submit or override legal thresholds.

curl -s \
  -H "Content-Type: application/json" \
  -H "X-VisaPathways-Enterprise-Token: $VP_API_KEY" \
  -X POST \
  "https://visapathways.co/api/v1/compliance/evaluate" \
  -d '{
    "target_jurisdiction": "CAN",
    "route_slug": "india-to-canada-study-permit",
    "rule_code": "CA-STUDY-FUNDS-2026",
    "evaluation_date": "2026-09-09",
    "candidate": {
      "available_funds": 25000,
      "funds_currency": "CAD"
    }
  }'

Verdicts are PASS, FAIL, or INSUFFICIENT_DATA. Successful evaluations are persisted under the authenticated tenant and return an evaluation_idthat can be used for later audit retrieval.

{
  "tenant": "your-tenant",
  "evaluation_id": "88b2f1a3-2a8a-49f5-954b-76a9d1b07c20",
  "route_slug": "india-to-canada-study-permit",
  "jurisdiction": "CAN",
  "verdict": "PASS",
  "reason_codes": ["FUNDS_MINIMUM"],
  "rule": {
    "id": "CA-STUDY-FUNDS-2026",
    "version": 2,
    "compiled_hash": "..."
  },
  "audit": {
    "profile_snapshot_hash": "...",
    "evidence_ids": ["..."],
    "trace": [
      {
        "sequence": 1,
        "node_type": "fact",
        "verdict": "PASS",
        "fact_key": "available_funds",
        "reason_code": "FUNDS_MINIMUM",
        "proposition_id": "...",
        "proposition_version": 2,
        "evidence_ids": ["..."]
      }
    ]
  }
}

POST rate limit: 30 requests per 60 seconds per API key.

Retrieve a historical evaluation audit

GET /api/v1/compliance/evaluations/{evaluation_id}returns the persisted decision, exact rule version, compiled hash, evidence identifiers, proposition trace, and profile snapshot hash. Retrieval is tenant-scoped: an authenticated tenant cannot retrieve another tenant's evaluation even if it knows the UUID.

curl -s \
  -H "X-VisaPathways-Enterprise-Token: $VP_API_KEY" \
  "https://visapathways.co/api/v1/compliance/evaluations/{evaluation_id}"

A missing evaluation and a cross-tenant evaluation both return 404 EVALUATION_NOT_FOUND. This prevents evaluation UUIDs from being used to probe another customer's audit history.

Current compliance coverage

CA-STUDY-FUNDS-2026 evaluates the India to Canada study permit living-expense proof-of-funds proposition. Version 2 is effective from 1 September 2026 at CAD 23,448 for one applicant outside Quebec, excluding tuition and transportation; version 1 remains available for historical evaluation dates. The UK Skilled Worker pilot uses UK-SW-MAINTENANCE-EVIDENCE-2026 for the maintenance-evidence paths backed by the published GOV.UK proposition set. Coverage remains proposition-by-proposition; neither rule is a complete visa eligibility decision.

Errors

  • 401 invalid or expired enterprise token
  • 400 invalid request or legal-threshold injection
  • 404 unpublished/unknown route or inaccessible evaluation audit
  • 409 rule not published, route/rule mismatch, or effective-window miss
  • 429 rate limited
  • 500 generic server failure; internal database details are not exposed

Limitations

Coverage is proposition-by-proposition. A published catalog route may have limited ledger coverage. Versioning is API v1 plus immutable compiled hashes on each rule version. VisaPathways provides structured compliance intelligence and deterministic rule evaluation; the API is not a visa decision and is not a second visa database.

Try compliance demoDeveloper sandboxPricingBack to Route Intelligence