YourVisa.ai docs

Quick Start Guide

curl -X POST "https://api.yourvisa.ai/unprotected/generate-programmatic-token" -H "Content-Type: application/json" -d '{"key": "your-api-key","secret": "your-api-secret"}'

curl -X GET "https://api.yourvisa.ai/agents-api/get-products-from-countries?from=IL&to=IN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Base URL

All API requests should be made to the following base URL:

Authentication

Most endpoints require authentication using a Bearer token. Include the token in the Authorization header of your requests:

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

• 200Success - Request completed successfully
• 400Bad Request - Invalid parameters or missing required fields
• 401Unauthorized - Invalid or expired access token
• 404Not Found - Resource not found
• 500Internal Server Error - Something went wrong on our end

Generate programmatic token

Exchange an Agents API key and secret for a JWT access token (valid 12 hours). Send either production or sandbox credentials — the environment is inferred from which key matches in the database. Do not send an environment field. When sandbox credentials match, the response includes isApiSandbox: true and the JWT carries the same flag so bookings created with that token are marked as test.

Request Body

Responses

Get products from countries

Parameters

Response Types

Response type - Get products from countries

Responses

Get supported destination country codes

Returns distinct ISO 3166-1 alpha-2 destination country codes that have visa products with isSupportedVisa true for the given origin country. The origin country is never included as a destination.

Parameters

Responses

Get specific product details

Parameters

Responses

Create a new booked visa product

Commit a new visa booking with customer details via API. The combination isPaidByCustomer=true with isFilledByCustomer=false (customer pays, agency fills) is not supported and returns 400. When corporateIdForCharging is provided, the booking is organization-paid and billed to that corporate (balance rolling or back-to-back per corporate billing settings). The agency must have isAllowedToChargeCorporatesViaApi enabled by YourVisa.ai admin. If the Bearer token was issued from sandbox API credentials (isApiSandbox: true from POST /unprotected/generate-programmatic-token), the booking is automatically marked as a test visa and balance charges are skipped.

Request Body

Responses

Generate application link for an existing booking

Generate an application URL with embedded token for an already-created booked product. Use this after creating a booking via POST /agents-api/commit-new-visa, or after receiving a bookedProductId from an instant-payment handoff. Set isIframe to true (default) for an iframe-ready URL, or false for the regular visa-wizard URL. Note: this link is only valid for visa applications that have not yet been submitted. Environment is inferred from the Bearer token: sandbox tokens may only generate links for test bookings; production tokens may only generate links for non-test bookings.

Request Body

Responses

Get history of products

Returns booked products for the authenticated agency. Optional filters are combined with AND. Traveler fields query applicantDetails on each booking. Each item includes paymentDetails (visa costs and who pays). If YourVisa admin enables applicant-data sharing for the agency, each item also includes full applicantDetails and time-limited download URLs for applicantUploads. Download URLs expire after 5 minutes and can be fetched with a normal HTTPS GET. Results are sorted by dateCreated descending (newest first). At most 100 items are returned. Environment is inferred from the Bearer token: sandbox tokens (isApiSandbox: true from generate-programmatic-token) return only test bookings; production tokens return only non-test bookings.

Parameters

Responses

Details

Download eVisa document for a booking

Returns a short-lived presigned URL to download the eVisa document for a booked product. The booking must belong to the authenticated agency. Non-manager agents can only access bookings they created. Returns 404 when the booking has no eVisa document attached yet. Environment is inferred from the Bearer token: sandbox tokens may only download eVisas for test bookings; production tokens may only download eVisas for non-test bookings.

Parameters

Responses

Create a connected corporate account

Creates a corporate under your agency and your partner corporate identifier. The identifier is stored as affiliatePartnerCorporateKey and can be used with corporateIdentifier on other corporate endpoints. The contact person you provide is also created as the corporate manager.

Request Body

Responses

List agency corporates

Lists corporates for the authenticated agency. Optional filters are query parameters (no request body). Up to 100 results per page, sorted by newest first. hasPaymentMethod is true when the corporate has billing set up to pay for bookings.

Parameters

Responses

Corporate payment link setup

Creates a secure link for the corporate manager to add a credit card on a YourVisa-hosted page. The link expires 12 hours after creation. corporateIdentifier accepts either the YourVisa corporate ObjectId or your partner corporate identifier. Set isEmbeddedInPartnerPage to true when embedding the setup page in your own site via iframe or mobile WebView—the returned URL targets /iframe/corporate-payment-setup/{token}, a navbar-free layout that shows the YourVisa.ai logo and legal policy links. The manager must accept YourVisa.ai terms before saving a card. After the manager saves a card, the embedded page emits a corporate_payment_method_saved host event. Optional langKey sets the UI language on the setup page (defaults to en).

Request Body

Responses

Details

POST /agents-api/create-corporate-payment-setup-link
{
  "corporateIdentifier": "acme-001",
  "isEmbeddedInPartnerPage": true,
  "langKey": "he"
}

Use setupUrl from the 201 response (targets /iframe/corporate-payment-setup/{token}).

<iframe
  src="{setupUrl}"
  width="100%"
  height="700"
  frameborder="0"
  style="border: none; border-radius: 8px;"
></iframe>

window.addEventListener("message", (event) => {
  // Optional but recommended: verify the iframe origin in production
  if (event.origin !== "https://www.yourvisa.ai") {
    return;
  }

  if (
    event.data?.source === "yourvisaai-iframe" &&
    event.data?.event === "corporate_payment_method_saved"
  ) {
    console.log("Card saved:", event.data.data);
  }
});

<WebView
  source={{ uri: setupUrl }}
  onMessage={(event) => {
    const payload = JSON.parse(event.nativeEvent.data);
    if (
      payload?.source === "yourvisaai-iframe" &&
      payload?.event === "corporate_payment_method_saved"
    ) {
      console.log("Card saved:", payload.data);
    }
  }}
/>

Details

Details

Details

Details

Details

Details

Details

Details

Example Response

{
  "mcpServers": {
    "YourVisa.ai": {
      "url": "https://mcp.yourvisa.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer yv_mcp_your_key_here"
      }
    }
  }
}

Details

Example Response

{
  "toCountry": "US",
  "fromCountry": "IL",
  "productId": "66a9ebe9572eb2904562c3ae",
  "bookedProductId": "66b0aae9572eb2904562c3af",
  "customKeys": {
    "customKey1": "travel-file-9",
    "customKey2": "string",
    "customKey3": "string",
    "customKey4": "string",
    "customKey5": "string"
  },
  "dateCreated": 1710000000000,
  "paymentDetails": {
    "currency": "USD",
    "govVisaCost": 35,
    "productServiceFee": 100,
    "partnerServiceFee": 0,
    "processingSpeedFee": 20,
    "partnerProcessingSpeedFee": 0,
    "totalCost": 155,
    "paymentStatus": "PAID",
    "paidBy": "AGENT"
  },
  "applicantDetails": {},
  "applicantUploads": {}
}