{
  "openapi": "3.1.0",
  "info": {
    "title": "ImmigrationPulse",
    "description": "Global immigration intelligence API serving 281M+ migrants. 11 endpoints covering visa requirements, PR pathways, points calculators (Express Entry CRS, SkillSelect), digital nomad visas, citizenship by investment, USCIS status, and immigrant rights \u2014 in 18 languages. All endpoints require x402 micropayment (USDC on Base).",
    "version": "1.1.0",
    "contact": {
      "url": "https://immigrationpulse.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://immigrationpulse.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Call without header to receive 402 with payment requirements. Sign and retry."
      }
    }
  },
  "security": [
    {
      "x402": []
    }
  ],
  "paths": {
    "/api/visa": {
      "get": {
        "operationId": "getVisa",
        "summary": "Visa requirements \u2014 any nationality + any destination",
        "description": "Complete visa intelligence for any nationality/destination pair. Returns all available visa categories (work, tourist, study, family, investor, digital nomad), eligibility requirements, work authorization rights, processing times, government fees, official application URLs, and common refusal reasons. Works for every country pair in the world. x-agent-use-case: on-demand when a user asks about moving, working, or traveling to any country.",
        "parameters": [
          {
            "name": "nationality",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Indian"
          },
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Canada"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "work",
                "tourist",
                "study",
                "family",
                "investor",
                "nomad"
              ],
              "default": "all"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "BCP-47 language code (e.g. es, fr, pt, hi, zh, ar)"
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Visa categories, requirements, work rights, fees, processing times, refusal risks, official URLs"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Follow with /api/pathway for permanent residency roadmap, or /api/cost for detailed fee breakdown"
      }
    },
    "/api/pathway": {
      "get": {
        "operationId": "getPathway",
        "summary": "Permanent residency roadmap \u2014 every pathway ranked for nationality + destination",
        "description": "Complete roadmap to permanent residency (green card, PR, ILR, etc.) for any nationality/destination pair. Returns every available pathway ranked by feasibility \u2014 Express Entry, EB-1/EB-2/EB-3, family sponsorship, investor programs, provincial/state nominees, etc. Includes estimated timelines, point scores, occupation matching, required documentation, and path to citizenship. Occupation and education inputs improve accuracy. Includes Boundless + CitizenPath filing service links for immediate next steps. x-agent-use-case: on-demand when a user asks how to get permanent residency in any country.",
        "parameters": [
          {
            "name": "nationality",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Filipino"
          },
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Canada"
          },
          {
            "name": "occupation",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Job title or NOC/SOC code \u2014 improves pathway matching"
          },
          {
            "name": "education",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Highest education level (e.g. bachelor, master, PhD)"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked PR pathways with timelines, requirements, and filing service links"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.2,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Follow with /api/cost for full cost breakdown including attorney fees"
      }
    },
    "/api/nomad": {
      "get": {
        "operationId": "getNomad",
        "summary": "Digital nomad visa finder \u2014 50+ countries ranked by income threshold + lifestyle",
        "description": "Finds the best digital nomad visas for a remote worker based on income level, nationality, and lifestyle preference. Returns 50+ countries with nomad/remote work visa programs ranked by: income requirement, cost of living, tax treatment, visa duration, path to residency, and internet quality. Filters available for region (Europe/Asia/LatAm/MENA) and priority (tax-free, fastest, EU access, cheapest). x-agent-use-case: on-demand for any remote worker or freelancer asking where they can legally work abroad.",
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "3500",
            "description": "Monthly income in USD"
          },
          {
            "name": "nationality",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "American"
          },
          {
            "name": "preference",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "balanced",
                "tax_free",
                "low_cost",
                "europe",
                "asia",
                "fastest"
              ]
            }
          },
          {
            "name": "region",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by region (e.g. Europe, Southeast Asia, Latin America, Caribbean)"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked nomad visa options with requirements, costs, and lifestyle context"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with RiskPulse /api/risk/nomad for 7-dimension safety + lifestyle score on any destination"
      }
    },
    "/api/citizenship": {
      "get": {
        "operationId": "getCitizenship",
        "summary": "Citizenship by investment, ancestry, and naturalization intelligence",
        "description": "Comprehensive citizenship intelligence across four pathways: (1) Investment \u2014 all active CBI programs globally (St Kitts, Malta, Vanuatu, Turkey, etc.) with minimum investment amounts, processing times, and due diligence requirements; (2) Ancestry \u2014 European and other ancestry citizenship programs (Italy, Ireland, Portugal, Germany, Poland, etc.) with bloodline requirements and documentation needed; (3) Naturalization \u2014 residence requirements by country for standard naturalization; (4) Second passport strategy \u2014 best combinations for travel freedom and tax optimization. x-agent-use-case: on-demand for HNWIs, expats, or anyone researching second passports.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "investment",
                "ancestry",
                "naturalization",
                "second"
              ]
            }
          },
          {
            "name": "budget",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Budget in USD for investment citizenship (e.g. 150000, 500000, 1000000)"
          },
          {
            "name": "ancestry",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Country for ancestry citizenship check (e.g. Italy, Ireland, Germany)"
          },
          {
            "name": "nationality",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Citizenship programs with investment amounts, timelines, and strategic recommendations"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.2,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "USCIS case status decoder with processing time context",
        "description": "Decodes USCIS case status messages into plain English with specific next-step guidance. Enter a receipt number (MSCxxxxxxxx, SRCxxxxxxxx, LINxxxxxxxx, EACxxxxxxxx, IOExxxxxxxx) and/or a status message to understand: what the status means, what USCIS is doing, what action (if any) you need to take, estimated time until next update, and whether to be concerned. Includes real USCIS processing time data from the USCIS API. Returns official USCIS case status portal and Boundless processing time tracker links. x-agent-use-case: on-demand when an immigrant gets a confusing USCIS notice or status update.",
        "parameters": [
          {
            "name": "receipt",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "USCIS receipt number (e.g. MSC2190012345, SRC2112345678)"
          },
          {
            "name": "form",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Form type (e.g. I-485, I-130, I-765, N-400, I-140, I-539)"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Status message to decode (e.g. 'Case Was Received', 'Request for Evidence', 'Case Was Approved')"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status explanation, next steps, processing time context, resource links"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/bulletin": {
      "get": {
        "operationId": "getBulletin",
        "summary": "US Visa Bulletin decoder \u2014 priority dates, filing chances, wait estimates",
        "description": "Decodes the monthly USCIS Visa Bulletin for employment-based (EB-1 through EB-5) and family-based (F-1 through F-4) preference categories. Enter a preference category and country of chargeability to get: current cutoff date, whether you can file for adjustment of status, estimated wait time based on historical movement, and strategic advice (e.g. whether to file under Dates for Filing vs Final Action Dates). Particularly valuable for India/China EB-2/EB-3 backlog which can span decades. x-agent-use-case: on-demand for employment-based green card applicants monitoring their priority date.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "EB-2",
            "description": "Preference category: EB-1|EB-2|EB-3|EB-4|EB-5|F-1|F-2A|F-2B|F-3|F-4"
          },
          {
            "name": "chargeability",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "India",
            "description": "Country of chargeability (usually birth country)"
          },
          {
            "name": "priority_date",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Your priority date (YYYY-MM-DD) \u2014 enables personalized filing eligibility check"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Priority date analysis, filing eligibility, wait estimate, strategic advice"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/retirement": {
      "get": {
        "operationId": "getRetirement",
        "summary": "Global retirement visa intelligence \u2014 best countries for retirees",
        "description": "Comprehensive retirement destination analysis for any nationality at any budget level. Ranks countries with retirement visa programs (Panama Pensionado, Portugal D7, Portugal NHR, Mexico Temporal Residente, Costa Rica Pensionado, Ecuador Jubilado, Thailand LTR, etc.) by healthcare quality, cost of living, tax treatment, English availability, safety, climate, and path to permanent residency. Filters available for priority preferences. x-agent-use-case: on-demand for pre-retirees and retirees exploring international retirement.",
        "parameters": [
          {
            "name": "nationality",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "American"
          },
          {
            "name": "budget",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2500",
            "description": "Monthly income/pension budget in USD"
          },
          {
            "name": "priority",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "balanced",
                "healthcare",
                "tax_free",
                "english",
                "eu_access",
                "cheapest"
              ]
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked retirement destinations with visa programs, healthcare, costs, and quality of life"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with TaxPulse /api/tax/expat for tax implications of retiring abroad"
      }
    },
    "/api/compare": {
      "get": {
        "operationId": "getCompare",
        "summary": "Side-by-side immigration comparison across multiple destination countries",
        "description": "Compares immigration options across 2\u20135 destination countries for a specific nationality and optional occupation. Head-to-head comparison of: ease of immigration, PR timeline, work authorization speed, family inclusion, salary requirements, language requirements, cost of living, quality of life, and long-term citizenship pathway. Returns a ranked recommendation and explains which destination wins for different priorities (fastest path, highest quality of life, best for families, etc.). x-agent-use-case: on-demand when someone is deciding between multiple destination countries for immigration.",
        "parameters": [
          {
            "name": "nationality",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Nigerian"
          },
          {
            "name": "destinations",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "UK,Canada,Germany",
            "description": "Comma-separated destination countries (2\u20135)"
          },
          {
            "name": "occupation",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Job title \u2014 improves pathway accuracy"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Side-by-side immigration comparison with ranked recommendation"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/rights": {
      "get": {
        "operationId": "getRights",
        "summary": "Immigrant rights by country and visa type",
        "description": "Comprehensive immigrant rights intelligence for a specific visa status in a specific country. Covers: work authorization (full/restricted/none), portability (can you change jobs?), travel restrictions (reentry permits, advance parole), path to permanent residency, healthcare and benefits eligibility, family petition rights, enforcement protections, anti-discrimination laws, and legal resources if rights are violated. x-agent-use-case: on-demand when an immigrant needs to understand their rights or limitations under a specific visa status.",
        "parameters": [
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "United States"
          },
          {
            "name": "visa_status",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "H-1B",
            "description": "Visa type or immigration status (e.g. H-1B, F-1, Green Card, TN, Skilled Worker, ILR)"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rights, restrictions, and protections for this visa status in this country"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/cost": {
      "get": {
        "operationId": "getCost",
        "summary": "Complete immigration cost breakdown \u2014 government fees + attorney + hidden costs",
        "description": "Full immigration cost model for any visa type and destination. Breaks down: USCIS/government filing fees (with biometrics, medical exam, and translation costs), attorney fee ranges for this case type, medical examination fees, document authentication/apostille costs, hidden costs (EAD, AP, photos, translations), family multiplier costs, and total realistic budget range. Includes fee waiver eligibility check and Boundless/CitizenPath service links as alternatives to full-cost attorneys. Includes Wise/Remitly links for cost-effective international payments. x-agent-use-case: on-demand when someone is budgeting for an immigration process.",
        "parameters": [
          {
            "name": "visa_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "I-485",
            "description": "Visa or form type (e.g. I-485, EB-2, H-1B, F-1, Canada Express Entry, UK Skilled Worker)"
          },
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "United States"
          },
          {
            "name": "with_attorney",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Include attorney fee estimate (default: true)"
          },
          {
            "name": "family_size",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Number of dependents to include in cost model"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Itemized cost breakdown, total range, fee waiver check, filing service links, money transfer links"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/points": {
      "get": {
        "operationId": "getPointsEstimate",
        "summary": "Skilled-worker points calculator \u2014 Canada Express Entry CRS, Australia SkillSelect, UK PBS, Germany Chancenkarte, Austria Red-White-Red Card",
        "description": "Estimates your score in any major points-based skilled immigration system, identifies gap to current invite cut-off, and provides a ranked improvement roadmap. $0.10 per request via x402.",
        "x402": {
          "price": "$0.10",
          "network": "eip155:8453",
          "currency": "USDC"
        },
        "parameters": [
          {
            "name": "system",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "express-entry",
                "skillselect",
                "uk-pbs",
                "germany",
                "nz",
                "austria",
                "any"
              ],
              "default": "express-entry"
            },
            "description": "Which immigration points system to evaluate. Use 'any' to assess all relevant systems."
          },
          {
            "name": "age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Applicant age in years (e.g. '31')"
          },
          {
            "name": "education",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "phd",
                "masters",
                "bachelors",
                "diploma",
                "trade",
                "secondary"
              ]
            },
            "description": "Highest level of education completed"
          },
          {
            "name": "clb",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Canadian Language Benchmark score (for Express Entry, e.g. '9'). CLB 9 = IELTS 7.0; CLB 10 = IELTS 7.5+."
          },
          {
            "name": "ielts",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Overall IELTS band score (e.g. '7.5') \u2014 used if clb not provided"
          },
          {
            "name": "work_years",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Years of skilled work experience outside the destination country"
          },
          {
            "name": "local_work",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Years of work experience inside the destination country"
          },
          {
            "name": "job_offer",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "description": "Whether applicant has a valid job offer from a qualifying employer"
          },
          {
            "name": "nomination",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "description": "Whether applicant has a provincial/state nomination (adds +600 CRS for Canada)"
          },
          {
            "name": "partner",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "description": "Whether applicant has a spouse/common-law partner with qualifying skills/language"
          },
          {
            "name": "occupation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Job title or NOC/ANZSCO occupation code (e.g. 'software engineer', '2173')"
          },
          {
            "name": "nationality",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Applicant nationality (for context on restrictions)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "en"
            },
            "description": "Response language (BCP-47 code, e.g. 'hi' for Hindi, 'zh' for Chinese)"
          }
        ],
        "responses": {
          "200": {
            "description": "Points estimate with score breakdown, gap to current cut-off, and improvement roadmap",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "system": {
                      "type": "string"
                    },
                    "estimated_score": {
                      "type": "integer"
                    },
                    "maximum_possible": {
                      "type": "integer"
                    },
                    "score_breakdown": {
                      "type": "array"
                    },
                    "eligibility_status": {
                      "type": "string",
                      "enum": [
                        "eligible",
                        "eligible_with_improvements",
                        "borderline",
                        "not_eligible"
                      ]
                    },
                    "recent_cutoff": {
                      "type": "object"
                    },
                    "gap_to_cutoff": {
                      "type": "integer"
                    },
                    "invitation_likelihood": {
                      "type": "string"
                    },
                    "top_improvements": {
                      "type": "array"
                    },
                    "alternative_systems": {
                      "type": "array"
                    },
                    "filing_services": {
                      "type": "array"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required \u2014 x402 payment details in PAYMENT-REQUIRED header"
          }
        }
      }
    }
  }
}