YourVisa Travel Visa MCP

Read-only remote MCP server that lets AI assistants look up visa, eVisa, ETA and ESTA requirements and fees by country and get official application links. API key required.

View on yourvisa.aiTry this MCPSponsored

Hosted MCP Server

npx add-mcp 'https://mcp.yourvisa.ai/api/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

Base URL:

https://api.yourvisa.ai

Building an AI-powered travel or immigration assistant? Read our story on how a Travel Visa MCP server stopped an agency's chatbot from giving wrong visa answers, and our engineering walkthrough on MCP Server Integration for travel documentation across e-visa, ETA and ETIAS.

Welcome to YourVisa.ai docs

This comprehensive API documentation will guide you through integrating our visa services into your application. Whether you're a beginner or an experienced developer, you'll find everything you need to get started.

Fast & Reliable

Quick response times with 99.9% uptime guarantee

Secure

Enterprise-grade security with OAuth 2.0 authentication

Well Documented

Clear examples and detailed explanations for every endpoint

Quick Start Guide

1

Get Your API Credentials

Sign up for an account and generate your production and/or sandbox API key and secret from the dashboard.

Key: your-api-key Secret: your-api-secret

Generate an Access Token

POST your key and secret to obtain a bearer token. The response includes agencyId and isApiSandbox (true for sandbox credentials, false for production). Do not send an environment field — it is inferred from which credentials match.

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"}'

Make Your First API Call

Use the token to authenticate your requests to protected endpoints.

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:

https://api.yourvisa.ai

Authentication

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

Authorization: Bearer YOUR_ACCESS_TOKEN

Important: Keep your API credentials secure. Never expose them in client-side code or public repositories. Use sandbox credentials for integration testing; sandbox tokens mark bookings as test and skip balance charges.

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

Need Help?

If you have questions or need assistance, don't hesitate to reach out:

post /unprotected/generate-programmatic-token

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

Schema: GenerateProgrammaticToken

key Requiredstring

Production or sandbox API key

secret Requiredstring

Matching production or sandbox API secret

Responses

200 Successful response

Schema: GenerateProgrammaticTokenResponse

success boolean

Default: true

token string

JWT access token valid for 12 hours

agencyId string

ID of the agency associated with the API credentials

isApiSandbox boolean

true when the provided key/secret are sandbox credentials; false for production. Sandbox tokens mark bookings created via the Agents API as test and skip balance charges.

Example false

400 Bad request

Schema: GenerateProgrammaticTokenBadRequest

success boolean

Default: false

message string

Possible values:

Missing fieldsUser with programmatic access doesn't exist

404 Not found

500 Internal server error

Try it Out

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

get /agents-api/get-products-from-countries?from={from}&to={to}

Get products from countries

Requires Authentication (Bearer Token)

Parameters

from Requiredpathstring

Country of origin

to Requiredpathstring

Destination country

currency pathstring

Optional display currency (supported ISO 4217 code). When provided, each product paymentDetails includes displayPricing with converted amounts.

Possible values:

AUD BRL CAD CHF CNY CZK DKK EGP ETB EUR GBP GHS HKD HUF IDR ILS INR ISK JPY KES KRW MAD MXN MYR NGN NOK NZD PHP PLN RON SEK SGD THB TND TRY TZS UGX USD XAF XOF ZAR

Country codes string

AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CK, CR, CI, HR, CU, CW, CY, CZ, CD, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, KP, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, KR, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, VG, UA, AE, GB, US, UM, UY, VI, UZ, VU, VA, VE, VN, WF, EH, YE, ZM, ZW

Response Types

Response type - Get products from countries

Responses

200 Successful response

Schema: GetProductsFromCountriesSupportedResponse

success boolean

Default: true

products array

Array of object(click to see properties)

400 Bad request

Schema: GetProductsFromCountriesBadRequest

success boolean

Default: false

message string

Possible values:

Country of origin (from) or destination country (to) is not providedCountry code (from or to) is not validCurrency code is not valid. Supported values: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EGP, ETB, EUR, GBP, GHS, HKD, HUF, IDR, ILS, INR, ISK, JPY, KES, KRW, MAD, MXN, MYR, NGN, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TND, TRY, TZS, UGX, USD, XAF, XOF, ZAR

401 Unauthorized

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

404 Not found

500 Internal server error

Try it Out

curl -X GET "https://api.yourvisa.ai/agents-api/get-products-from-countries?from={from}&to={to}" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

get /agents-api/get-supported-destinations?from={from}

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.

Requires Authentication (Bearer Token)

Parameters

from Requiredpathstring

Country of origin

Responses

200 Successful response

Schema: GetSupportedDestinationsResponse

success boolean

Default: true

countryCodes array

Array of string

400 Bad request

Schema: GetSupportedDestinationsBadRequest

success boolean

Default: false

message string

Possible values:

Country of origin (from) is not providedCountry code (from) is not valid

401 Unauthorized

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

500 Internal server error

Try it Out

curl -X GET "https://api.yourvisa.ai/agents-api/get-supported-destinations?from={from}" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

get /agents-api/get-specific-product-details?productId=66a9ebe9572eb2904562c3ad

Get specific product details

Requires Authentication (Bearer Token)

Parameters

productId Requiredpathstring

ID of the product

Responses

200 Successful response

Schema: GetSpecificProductDetailsResponse

success boolean

Default: true

productInputDetails array

Array of object(click to see properties)

productDetails object

400 Bad request

Schema: GetSpecificProductDetailsBadRequest

success boolean

Default: false

message string

401 Unauthorized

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

404 Not found

500 Internal server error

Try it Out

curl -X GET "https://api.yourvisa.ai/agents-api/get-specific-product-details?productId=66a9ebe9572eb2904562c3ad" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

post /agents-api/commit-new-visa

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.

Requires Authentication (Bearer Token)

Request Body

Schema: CommitNewVisaRequest

productId Requiredstring

The ID of the visa product

isPaidByCustomer boolean

Whether the customer will pay (true) or the agent will pay (false). Cannot be true when isFilledByCustomer is false.

isFilledByCustomer boolean

Whether the customer will fill the form (true) or the agent will fill it (false). Cannot be false when isPaidByCustomer is true.

customerFirstName Requiredstring

Customer's first name

customerLastName Requiredstring

Customer's last name

customerEmail Requiredstring

Customer's email address

voucherInvoiceNumber string

Optional voucher or invoice reference stored with the booking

Example "INV-2026-001"

travelFileNumber string

Optional Travel CRM travel file number linked to this booking

Example "1252813"

messageForTraveler string

Optional message included in the traveler application email when isFilledByCustomer is true. Letters, numbers, spaces, and basic punctuation (.,!? ' -) only.

Example "Please complete the form and upload a clear passport scan."

preferredLanguage string

Optional language code for traveler-facing emails: en (English, default), de (Deutsch), es (Español), ru (Русский), he (עברית), ar (العربية), fr (Français)

Possible values:

endeesruhearfr

corporateIdForCharging string

Optional corporate ID to bill for this booking instead of the agency balance. Requires agency isAllowedToChargeCorporatesViaApi, the corporate must belong to the agency, and the corporate must have a valid payment setup (saved card for back-to-back, or auto top-up with saved card for balance rolling). When set, isPaidByCustomer is treated as false and the traveler email is added to the corporate whitelist.

Example "66a9ebe9572eb2904562c3ae"

customKeys object

Optional custom key-value pairs for tracking or metadata (maximum 5 keys). Example: {"customKey1": "customKey1 value", "customKey2": "customKey2 value", "customKey3": "customKey3 value", "customKey4": "customKey4 value", "customKey5": "customKey5 value"}

Responses

201 Successfully created booked product

Schema: CommitNewVisaResponse

success boolean

Example true

bookedProductId string

Example "66a9ebe9572eb2904562c3ae"

isPaymentTest boolean

true when the booking was created as a test visa (sandbox API credentials or agency/corporate integration test mode). Test bookings skip balance charges.

Example false

message string

Example "Visa booking created successfully"

400 Bad request - validation error

Schema: CommitNewVisaBadRequest

success boolean

message string

401 Unauthorized - invalid or missing token

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

403 Forbidden - agency not allowed to create agent-paid bookings

Schema: CommitNewVisaForbidden

success boolean

message string

Example "Your agency is not allowed to create agent-paid bookings"

404 Product or agency not found

Schema: CommitNewVisaNotFound

success boolean

message string

Try it Out

curl -X POST "https://api.yourvisa.ai/agents-api/commit-new-visa" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
  "productId": "string",
  "isPaidByCustomer": true,
  "isFilledByCustomer": true,
  "customerFirstName": "string",
  "customerLastName": "string",
  "customerEmail": "string",
  "voucherInvoiceNumber": "string",
  "travelFileNumber": "string",
  "messageForTraveler": "string",
  "preferredLanguage": "en",
  "corporateIdForCharging": "string",
  "customKeys": {
    "customKey1": "customKey1 value",
    "customKey2": "customKey2 value",
    "customKey3": "customKey3 value",
    "customKey4": "customKey4 value",
    "customKey5": "customKey5 value"
  }
}'

post /agents-api/get-application-link

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.

Requires Authentication (Bearer Token)

Request Body

Schema: GetApplicationLinkRequest

bookedProductId Requiredstring

The ID of the existing booked product. This can come from POST /agents-api/commit-new-visa or from a partner instant-payment return URL.

langKey string

Optional language preference for the application form: en (English, default), de (Deutsch), es (Español), ru (Русский), he (עברית), ar (العربية), fr (Français)

Possible values:

endeesruhearfr

isIframe boolean

Whether to generate an iframe URL (true, default) pointing to /iframe/visa-wizard, or a regular URL (false) pointing to /visa-wizard

Default:

Responses

200 Successfully generated application link

Schema: GetApplicationLinkResponse

success boolean

Example true

bookedProductId string

The ID of the booked product

Example "66a9ebe9572eb2904562c3ae"

applicationUrl string

The full URL including base domain.
With isIframe=true (default): https://www.yourvisa.ai/iframe/visa-wizard?productId=...&token=...
With isIframe=false: https://www.yourvisa.ai/visa-wizard?productId=...&token=...

Example "https://www.yourvisa.ai/iframe/visa-wizard?productId=66a9ebe9572eb2904562c3ad&token=eyJhbGc..."

path string

The path and query portion of the URL (everything after the base domain).
With isIframe=true (default): /iframe/visa-wizard?productId=...&token=...
With isIframe=false: /visa-wizard?productId=...&token=...

Example "/iframe/visa-wizard?productId=66a9ebe9572eb2904562c3ad&token=eyJhbGc..."

message string

Example "Application link generated successfully"

400 Bad request - validation error

Schema: GetApplicationLinkBadRequest

success boolean

message string

Possible values:

Missing required fieldsInvalid booked product IDInvalid agency ID

401 Unauthorized - invalid or missing token

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

403 Forbidden - booking does not belong to your agency

Schema: GetApplicationLinkForbidden

success boolean

message string

Possible values:

Booking does not belong to your agency

404 Booked product or agency not found

Schema: GetApplicationLinkNotFound

success boolean

message string

Possible values:

Booked product not foundAgency not found

Try it Out

curl -X POST "https://api.yourvisa.ai/agents-api/get-application-link" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
  "bookedProductId": "string",
  "langKey": "en",
  "isIframe": true
}'

get /agents-api/get-products-history

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.

Requires Authentication (Bearer Token)

Parameters

dateStart querystring

Optional lower bound on booking dateCreated (ISO date or datetime). Omit with dateEnd to leave range open on the lower side.

dateEnd querystring

Optional upper bound on booking dateCreated (ISO date or datetime). Omit with dateStart to leave range open on the upper side.

bookedProductId querystring

MongoDB ObjectId of the booked product (24-character hex)

statusCode query

Agency-facing booking status filter (same values as status on each item).

Possible values:

waitingForTravelerToFill pleaseFillVisaDetails wereProcessingYourVisa missingVisaDetails waitingForTravelerResponse handledByOurTeam governmentReviewing applicationNotApproved fraudFlagged visaProcessFinished refundInProgress refundCompleted

fromCountry querystring

Origin country on the booking (case-insensitive exact match)

toCountry querystring

Destination country on the booking (case-insensitive exact match)

visaType querystring

Visa type on the booking (case-insensitive exact match)

firstName querystring

Substring match on applicantDetails.firstName (case-insensitive)

lastName querystring

Substring match on applicantDetails.lastName (case-insensitive)

email querystring

Substring match on applicantDetails.email (case-insensitive)

customKey1 querystring

Exact match on customKeys.customKey1. Use for partner-defined tracking or lookup data.

customKey2 querystring

Exact match on customKeys.customKey2. Recommended for a partner external booking ID.

customKey3 querystring

Exact match on customKeys.customKey3. Recommended for a partner external traveler ID.

customKey4 querystring

Exact match on customKeys.customKey4. Recommended for a partner external trip ID.

customKey5 querystring

Exact match on customKeys.customKey5. Use for extra partner context when needed.

Responses

200 Successful response

Schema: GetHistoryOfProductsResponse

success boolean

Example true

message string

Present when no bookings match filters (success still true).

Example "There are no matching products"

bookedProducts array

Newest bookings first; capped at 100 items.

Array of object(click to see properties)

400 Bad request

Schema: GetHistoryOfProductsBadRequest

success boolean

Default: false

message string

Examples include invalid dateStart/dateEnd, start date after end date, invalid bookedProductId, invalid statusCode.

401 Unauthorized

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

404 Not found

500 Internal server error

Try it Out

curl -X GET "https://api.yourvisa.ai/agents-api/get-products-history" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Instant payments: complete applications inside your platform

Use this flow when you want the traveler to pay on YourVisa before the full visa application, then return to your platform and complete the application inside a YourVisa iframe.

Instant PaymentYour PlatformIframe

Details

Step 1: Check visa products

Call GET /agents-api/get-products-from-countries?from={from}&to={to} to find available products. Use the selected productId in the checkout entry URL.

Step 2: Start instant checkout

Send the traveler to https://www.yourvisa.ai/instant-visa-checkout (standalone) or https://www.yourvisa.ai/iframe/instant-visa-checkout (embedded in your site) with productId, affiliatedAgencyId, travelerClient, isInstantPayment=true, optional traveler prefill fields, and customKey1..5. productId is used on entry because bookedProductId does not exist until checkout creates the booking.

Step 2A: Web checkout URL

https://www.yourvisa.ai/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient= web &isInstantPayment=true&travelerFirstName={firstName}&travelerLastName={lastName}&travelerEmail={email}&travelerPhone={phone}&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId}&customKey4={externalTripId}&customKey5={extraContext}

Step 2A-iframe: Embedded web checkout URL

https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient= web &isInstantPayment=true&travelerFirstName={firstName}&travelerLastName={lastName}&travelerEmail={email}&travelerPhone={phone}&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId}&customKey4={externalTripId}&customKey5={extraContext}

Step 2B: App checkout URL

https://www.yourvisa.ai/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient= app &isInstantPayment=true&travelerFirstName={firstName}&travelerLastName={lastName}&travelerEmail={email}&travelerPhone={phone}&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId}&customKey4={externalTripId}&customKey5={extraContext}

Step 2C: Checkout parameters

travelerClient is web or app. Use web when the traveler starts from your website. Use app when the traveler starts from your mobile app and payment opens in an external browser tab. travelerFirstName, travelerLastName, travelerEmail, and travelerPhone are optional prefill fields. customKey1..5 are your reference fields, for example external user ID, order ID, traveler ID, trip ID, campaign, or source.

Step 3: After payment

Behavior depends on your agency instant-payment handoff setting (configured by YourVisa — contact us to enable or change): • Continue on YourVisa (default): the traveler continues the visa wizard on YourVisa. • Return to partner: the traveler sees a payment-complete screen instead of continuing on YourVisa. If YourVisa configured a partner redirect URL for your agency, they are sent there after a short countdown with bookedProductId, productId, paymentStatus=paid, and any non-empty customKey1..5 — for both travelerClient=web and travelerClient=app. If no redirect URL is configured, they see a thank-you screen and return to your app or website on their own. Iframe embeds receive instant_payment_complete on the parent page when partner handoff is enabled. YourVisa also sends the traveler a payment-received confirmation email branded for your agency.

Step 3A: Web return URL example

https://partner.example.com/visa/payment-complete?bookedProductId={bookedProductId}&productId={productId}&paymentStatus=paid&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId} Redirect URLs are configured by YourVisa for your agency — contact support to request or update yours.

Step 3B: App booking lookup

After the traveler returns to your app, use your original custom keys to find the paid booking. Example: GET /agents-api/get-products-history?customKey1={externalUserId}&customKey2={externalBookingId}. Filters use exact matching, are scoped to your agency, and are combined with other optional filters using AND logic. Use the returned bookedProducts[0]._id as bookedProductId.

Step 4: Get iframe application link

Call POST /agents-api/get-application-link with {"bookedProductId": "66a9ebe9572eb2904562c3ae", "langKey": "en", "isIframe": true}. The response includes applicationUrl.

Step 5: Embed the iframe

<iframe src="{applicationUrl}" width="100%" height="700" frameborder="0"></iframe>

Step 6: Listen for completion

After YourVisa submits the application inside the iframe, it shows an Application submitted message and sends application_submitted to the parent page. Your platform owns what happens next: keep the iframe open, close it, or replace it with your own trip/application status screen.

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.

get /agents-api/download-evisa-document

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.

Requires Authentication (Bearer Token)

Parameters

bookedProductId Requiredquerystring

MongoDB ObjectId of the booked product (24-character hex)

Responses

200 Presigned download URL generated successfully

Schema: DownloadEvisaDocumentResponse

success boolean

Example true

data object

400 Bad request - missing or invalid bookedProductId

Schema: DownloadEvisaDocumentBadRequest

success boolean

Default: false

message string

Example "bookedProductId query parameter is required"

401 Unauthorized - invalid or missing token

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

403 Forbidden - booking not found or access denied

Schema: DownloadEvisaDocumentForbidden

success boolean

Default: false

message string

Example "Booking not found or access denied"

404 No eVisa document available for this booking

Schema: DownloadEvisaDocumentNotFound

success boolean

Default: false

message string

Example "No eVisa document available for this booking"

errorCode string

Possible values:

EVISA_DOCUMENT_NOT_AVAILABLEEVISA_DOCUMENT_FILE_NOT_FOUND

hasEvisaDocument boolean

false when the booking has no eVisa attached yet; true when metadata exists but the file is missing

Example "false"

Try it Out

curl -X GET "https://api.yourvisa.ai/agents-api/download-evisa-document" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

post /agents-api/create-corporate

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.

Requires Authentication (Bearer Token)

Request Body

Schema: CreateCorporateRequest

corporateName Requiredstring

partnerCorporateIdentifier Requiredstring

Partner-owned corporate identifier unique within your agency

contact Requiredobject

Primary contact who is also created as the corporate manager

Responses

201 Corporate created successfully

Schema: CreateCorporateResponse

success boolean

Example true

corporateId string

partnerCorporateIdentifier string

400 Validation error

Schema: BadRequest

message string

errorCode string

Default: BadRequest

401 Unauthorized

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

409 Partner corporate identifier already in use

Schema: BadRequest

message string

errorCode string

Default: BadRequest

Try it Out

curl -X POST "https://api.yourvisa.ai/agents-api/create-corporate" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
  "corporateName": "string",
  "partnerCorporateIdentifier": "string",
  "contact": {}
}'

get /agents-api/get-corporates

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.

Example request URL

https://api.yourvisa.ai/agents-api/get-corporates?partnerCorporateIdentifier=acme-001&corporateName=Acme&page=1

Requires Authentication (Bearer Token)

Parameters

corporateId querystring

YourVisa corporate MongoDB ObjectId

partnerCorporateIdentifier querystring

Partner-owned corporate identifier (exact match)

corporateName querystring

Case-insensitive partial name match

page queryinteger

Page number (default 1)

Responses

200 Corporates listed successfully

Schema: GetCorporatesResponse

success boolean

Example true

corporates array

Array of object(click to see properties)

page integer

pageSize integer

totalCount integer

totalPages integer

400 Validation error

Schema: BadRequest

message string

errorCode string

Default: BadRequest

401 Unauthorized

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

Try it Out

curl -X GET "https://api.yourvisa.ai/agents-api/get-corporates?partnerCorporateIdentifier=acme-001&corporateName=Acme&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

post /agents-api/create-corporate-payment-setup-link

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).

Requires Authentication (Bearer Token)

Request Body

Schema: CreateCorporatePaymentSetupLinkRequest

corporateIdentifier Requiredstring

YourVisa corporate ObjectId or partner corporate identifier

isEmbeddedInPartnerPage boolean

When true, setupUrl targets /iframe/corporate-payment-setup/{token} for embedding in a partner page without the YourVisa navbar.

langKey string

Optional UI language for the setup page: en (English, default), de (Deutsch), es (Español), ru (Русский), he (עברית), ar (العربية), fr (Français)

Possible values:

endeesruhearfr

Responses

201 Setup link created successfully

Schema: CreateCorporatePaymentSetupLinkResponse

success boolean

Example true

token string

setupUrl string

Full URL to send the corporate manager

path string

Example "/corporate-payment-setup/abc123?langKey=de"

expiresAt string

Link expiry time (12 hours after creation)

corporateId string

partnerCorporateIdentifier stringnull

isEmbeddedInPartnerPage boolean

Whether the setup page is intended for iframe embedding

langKey string

Resolved UI language for the setup page

Possible values:

endeesruhearfr

400 Validation error

Schema: BadRequest

message string

errorCode string

Default: BadRequest

401 Unauthorized

Schema: Unauthorized

success boolean

Default: false

message string

Possible values:

You don't have credentialsYou don't have permissionInvalid access tokenYour access token is not valid or expired

403 Corporate is not configured for organization-paid billing

Schema: BadRequest

message string

errorCode string

Default: BadRequest

404 Corporate not found

Schema: BadRequest

message string

errorCode string

Default: BadRequest

Details

Step 1: Create embedded link

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}).

Step 2: Load the iframe

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

Step 3: Listen in browser (iframe parent)

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);
  }
});

Step 4: Listen in React Native WebView

<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);
    }
  }}
/>

Event structure

{source: "yourvisaai-iframe", event: "corporate_payment_method_saved", data: {corporateId: "...", corporateName: "...", timestamp: "2026-07-02T13:25:50.110Z"}}

When it fires

Only when isEmbeddedInPartnerPage was true on link creation and after the server confirms card save on POST /corporate-payment-setup/:token/complete.

Try it Out

curl -X POST "https://api.yourvisa.ai/agents-api/create-corporate-payment-setup-link" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
  "corporateIdentifier": "string",
  "isEmbeddedInPartnerPage": true,
  "langKey": "en"
}'

Creating a link for an affiliated agency with specific product

This section explains how to construct and use a specialized URL to embed the visa application for affiliated agencies and agents.

Affiliated Agency Usage

Details

Example URL with productId

https://www.yourvisa.ai/visa-wizard?productId={productId}&affiliatedAgencyId={affiliatedAgencyId}&affiliatedAgentId={affiliatedAgentId}&customKey1={value1}&customKey2={value2}

Example URL to any product

https://www.yourvisa.ai?affiliatedAgencyId={affiliatedAgencyId}&affiliatedAgentId={affiliatedAgentId}

Domain

https://www.yourvisa.ai/ - The base URL of the service, which should be embedded using an iframe or opened directly.

productId

Represents the unique ID of the product being booked.

affiliatedAgencyId

Represents the unique ID of the affiliated agency or partner integrating the service.

affiliatedAgentId

(Optional field) Identifies the specific agent within the affiliated agency who is generating the visa.

customKey1-5

(Optional) Custom tracking parameters. You can include up to 5 custom keys (customKey1, customKey2, customKey3, customKey4, customKey5) for additional tracking or identification purposes. These will be stored in the booking and sent via webhooks.

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.

Creating a custom traveler page link with pre-filled country information

This section explains how to construct a specialized URL that pre-fills the visa search with specific origin and destination countries, along with affiliated agency tracking.

Affiliated Agency UsageCustom Links

Details

Example URL with countries

https://www.yourvisa.ai/traveler/{from}/{to}?visaType={visaType}&affiliatedAgencyId={affiliatedAgencyId}&affiliatedAgentId={affiliatedAgentId}&customKey1={value1}&customKey2={value2}

Example URL minimal

https://www.yourvisa.ai/traveler/IL/US

Domain

https://www.yourvisa.ai/ - The base URL of the service.

from

(Required) Two-letter country code representing the traveler's origin country or passport nationality (e.g., 'IL' for Israel, 'US' for United States).

to

(Required) Two-letter country code representing the destination country (e.g., 'US' for United States, 'GB' for United Kingdom).

visaType

(Optional) Type of visa being requested (e.g., 'tourist', 'business', 'student'). If not specified, defaults to 'tourist'.

affiliatedAgencyId

Represents the unique ID of the affiliated agency or partner integrating the service.

affiliatedAgentId

(Optional field) Identifies the specific agent within the affiliated agency who is generating the visa.

customKey1-5

(Optional) Custom tracking parameters. You can include up to 5 custom keys (customKey1, customKey2, customKey3, customKey4, customKey5) for additional tracking or identification purposes. These will be stored in the booking and sent via webhooks.

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.

Interactive tool

Download the iframe tester

Get a self-contained HTML page to try every embedded iframe flow locally — visa search, wizard, instant checkout, corporate payment setup, and postMessage events.

Download iframe tester

Overview and host events

Embed YourVisa flows inside your website or mobile WebView without the YourVisa navbar or footer. Use /iframe/* URLs for embedding; use the non-iframe URLs when opening in a new browser tab. Payment surfaces embedded in an iframe (instant checkout, corporate card setup, and the visa wizard payment step) also show the YourVisa.ai logo and links to terms, privacy, refund, and cookie policies. Visa search and non-payment wizard steps do not include that payment chrome.

Embedded Iframe

Details

Iframe base path

All iframe routes live under https://www.yourvisa.ai/iframe/.... They suppress the main YourVisa navbar and footer.

Payment page branding

Embedded payment surfaces show the YourVisa.ai logo and legal policy links: /iframe/instant-visa-checkout, /iframe/corporate-payment-setup/{token}, and the payment step inside /iframe/visa-wizard. Visa search and other wizard steps do not.

Listen for events (browser)

window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if (event.data?.source !== "yourvisaai-iframe") { return; } console.log(event.data.event, event.data.data); });

Event: application_submitted

{source: "yourvisaai-iframe", event: "application_submitted", data: {bookedProductId: "...", productId: "...", timestamp: "2026-07-04T10:30:00.000Z", ...}} — fired after the traveler submits the visa application inside the iframe.

Event: instant_payment_complete

{source: "yourvisaai-iframe", event: "instant_payment_complete", data: {bookedProductId: "66a9ebe9572eb2904562c3ae", productId: "68e94b68f0022238439d7d4b", paymentStatus: "paid", redirectUrl: "https://partner.example.com/visa/payment-complete?...", timestamp: "2026-07-04T10:30:00.000Z"}} — fired immediately on the partner handoff payment-complete screen when instant checkout runs inside an iframe, before any automatic redirect. redirectUrl is included when configured.

Event: corporate_payment_method_saved

{source: "yourvisaai-iframe", event: "corporate_payment_method_saved", data: {corporateId: "...", corporateName: "...", timestamp: "2026-07-02T13:25:50.110Z"}} — fired after a corporate manager saves a card on the embedded payment-setup page.

React Native WebView

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

Optional query parameters

On /iframe/traveler, /iframe/visa-wizard, and /iframe/instant-visa-checkout you may append: customKey1..5, langKey (e.g. &langKey=he).

Language support (direct iframe URLs)

Append langKey as a query parameter on iframe URLs you build yourself. Supported values: en (default), de, es, ru, he, ar, fr. Traveler search: https://www.yourvisa.ai/iframe/traveler?affiliatedAgencyId={agencyId}&customKey1={value1}&langKey=he Instant checkout: https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&isInstantPayment=true&travelerClient=web&customKey1={value1}&langKey=de

Language support (visa wizard URL)

Append langKey as a query parameter when you build the iframe URL directly. https://www.yourvisa.ai/iframe/visa-wizard?productId={productId}&affiliatedAgencyId={agencyId}&customKey1={value1}&langKey=de

Language support (signed application link)

If you already have a bookedProductId and need a tokenized link, pass langKey in POST /agents-api/get-application-link. Use applicationUrl from the response as the iframe src.

Language support (corporate payment setup)

Pass langKey in POST /agents-api/create-corporate-payment-setup-link. The response setupUrl includes it when provided. {"corporateIdentifier": "acme-001", "isEmbeddedInPartnerPage": true, "langKey": "he"} Example setupUrl path: /iframe/corporate-payment-setup/{token}?langKey=he

Custom branding

If your agency has custom branding enabled, iframe routes automatically apply your branded experience.

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.

Visa application wizard

Embed the visa application wizard when you already know which product the traveler should apply for. Point the iframe at /iframe/visa-wizard with productId and your affiliatedAgencyId.

Embedded IframeVisa Application

Details

Direct iframe URL

https://www.yourvisa.ai/iframe/visa-wizard?productId={productId}&affiliatedAgencyId={agencyId}

Example

https://www.yourvisa.ai/iframe/visa-wizard?productId=68e94b68f0022238439d7d4b&affiliatedAgencyId={agencyId}&customKey1={value1}&langKey=he

Embed

<iframe src="https://www.yourvisa.ai/iframe/visa-wizard?productId={productId}&affiliatedAgencyId={agencyId}&customKey1={value1}&customKey2={value2}&langKey=en" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>

Required parameters

productId — the visa product the traveler is applying for. affiliatedAgencyId — your agency ID so the booking is attributed to your account.

Optional parameters

customKey1..5, langKey (e.g. &langKey=he).

Standalone vs iframe

Use /iframe/visa-wizard for embedding inside your site. Use /visa-wizard with the same query parameters when opening in a new browser tab.

Listen for completion

After submission, the iframe sends application_submitted to the parent page.

Already have a bookedProductId?

If the traveler already paid or you created a booking via API, use POST /agents-api/get-application-link with isIframe: true instead. That returns a signed applicationUrl with a token for the existing booking.

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.

Instant payment checkout

Embed instant payment when you already know the productId.

Load the checkout at /iframe/instant-visa-checkout inside your site or app. The page shows the YourVisa.ai logo and links to our legal policies.

After payment, your integration follows one of three paths — contact YourVisa to configure the option that fits your product.

Embedded IframeInstant Payment

Details

After payment — option 1: Redirect to your website

YourVisa sends the traveler to a redirect URL you provide in advance. Query parameters include bookedProductId, productId, paymentStatus=paid, and any non-empty customKey1..5. Works for both travelerClient=web and travelerClient=app. Contact YourVisa support to request or change your redirect URL — it cannot be set through the API.

After payment — option 2: Stay embedded (iframe event)

When checkout runs inside an iframe, your parent page receives an instant_payment_complete postMessage as soon as payment succeeds. Use this to close the iframe, show your own confirmation, or continue in your UI. See Listen for payment complete and Event: instant_payment_complete below.

After payment — option 3: Continue the visa wizard

The traveler moves straight into the YourVisa visa wizard in the same iframe or tab — no redirect and no partner handoff screen. No instant_payment_complete is sent at payment time. Listen for application_submitted after the traveler finishes and submits the visa form.

Combining options 1 and 2

When a redirect URL is configured, embedded checkout still fires instant_payment_complete immediately, shows a short payment-complete screen, then redirects inside the iframe after a few seconds. That gives your page time to close the iframe or handle the event before the redirect.

Embed checkout

<iframe id="yourvisa-instant-checkout" src="https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient=web&isInstantPayment=true&langKey=en&travelerFirstName={firstName}&travelerLastName={lastName}&travelerEmail={email}&travelerPhone={phone}&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId}&customKey4={externalTripId}&customKey5={extraContext}" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>

Required parameters

productId, affiliatedAgencyId, isInstantPayment=true, travelerClient (web or app).

Optional parameters

customKey1..5, langKey (e.g. &langKey=he), travelerFirstName, travelerLastName, travelerEmail, travelerPhone.

travelerClient

web — traveler starts from your website or embedded iframe. app — traveler starts from your native mobile app; payment may open in an external browser tab or WebView.

No redirect URL configured

If partner handoff is enabled but no redirect URL is set, travelers see a thank-you screen telling them payment was received and to return to your app or website. Find the paid booking with GET /agents-api/get-products-history or resume with POST /agents-api/get-application-link.

Listen for payment complete (browser)

window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if ( event.data?.source === "yourvisaai-iframe" && event.data?.event === "instant_payment_complete" ) { const { bookedProductId, productId, paymentStatus, redirectUrl } = event.data.data; console.log("Instant payment complete", { bookedProductId, productId, paymentStatus, redirectUrl }); // Close the iframe now, or let the traveler follow the in-iframe redirect } });

Event: instant_payment_complete

{source: "yourvisaai-iframe", event: "instant_payment_complete", data: {bookedProductId: "66a9ebe9572eb2904562c3ae", productId: "68e94b68f0022238439d7d4b", paymentStatus: "paid", redirectUrl: "https://partner.example.com/visa/payment-complete?...", timestamp: "2026-07-04T10:30:00.000Z"}} Fired immediately on the partner handoff payment-complete screen when checkout runs inside an iframe — before any automatic redirect. redirectUrl is included when YourVisa configured one for your agency.

Full integration example

<iframe id="yourvisa-instant-checkout" src="https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient=web&isInstantPayment=true&customKey1={externalUserId}&customKey2={externalBookingId}" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" ></iframe> <script> window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if (event.data?.source !== "yourvisaai-iframe") { return; } if (event.data.event === "instant_payment_complete") { const { bookedProductId, productId } = event.data.data; document.getElementById("yourvisa-instant-checkout").style.display = "none"; // Resume in your UI, or load the wizard iframe with POST /agents-api/get-application-link } }); </script>

Redirect URL example

https://partner.example.com/visa/payment-complete?bookedProductId={bookedProductId}&productId={productId}&paymentStatus=paid&customKey1={externalUserId}&customKey2={externalBookingId}

Event: application_submitted

{ "source": "yourvisaai-iframe", "event": "application_submitted", "data": { "bookedProductId": "6a493c9b8f46d0e57c31bd65", "productId": "68e94b68f0022238439d7d4b", "visaType": "tourist", "timestamp": "2026-07-04T17:08:29.646Z" } } Fired inside an iframe when the traveler submits the visa application after instant payment and continuing through the wizard. This is the completion signal for option 3 — not instant_payment_complete. applicantName may also be included when available.

Listen for application submitted (browser)

window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if ( event.data?.source === "yourvisaai-iframe" && event.data?.event === "application_submitted" ) { const { bookedProductId, productId, visaType } = event.data.data; console.log("Visa application submitted", { bookedProductId, productId, visaType }); // Close the iframe, show your own confirmation, or refresh trip status } });

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.

Corporate payment method setup

Embed the corporate card-setup page so a corporate manager can save a payment method inside your site. Requires POST /agents-api/create-corporate-payment-setup-link with isEmbeddedInPartnerPage: true. The embedded page shows the YourVisa.ai logo and legal policy links.

Embedded IframeCorporate

Details

Step 1: Create embedded link

POST /agents-api/create-corporate-payment-setup-link { "corporateIdentifier": "acme-001", "isEmbeddedInPartnerPage": true, "langKey": "he" } langKey is set in the request body. Use setupUrl from the 201 response as the iframe src (targets /iframe/corporate-payment-setup/{token}?langKey=he).

Step 2: Load the iframe

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

Optional parameters

langKey only — set in the POST body when creating the link (e.g. "langKey": "he"). The returned setupUrl includes it. customKey1..5 do not apply to this flow.

Step 3: Listen in browser

window.addEventListener("message", (event) => { 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); } });

When it fires

Only when isEmbeddedInPartnerPage was true on link creation and after the server confirms card save.

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.

MCP Server — connect AI assistants to YourVisa.ai

The YourVisa MCP (Model Context Protocol) server lets any compatible AI assistant — Claude Desktop, Cursor, and others — look up visa requirements, fees, and generate application links in real time. It is a remote HTTP service using the Streamable HTTP transport and requires an API key.

MCPAI Integration

Details

1. Get an API key

Log in to your YourVisa.ai account, go to Dashboard → MCP API tab, and click 'New Key'. Copy and save it — it is shown only once.

2. Add to your MCP client config

Add the config block shown below to your MCP client configuration file (e.g. claude_desktop_config.json for Claude Desktop, or the MCP settings in Cursor).

3. Available tools

search_visas · get_visa_details · get_visa_requirements · get_visa_fees · get_application_link · get_country_info

4. Stateless & read-only

The MCP server only reads data. No bookings or writes are performed via MCP.

5. Rate limits

Free tier: 60 requests / minute.

Example Response

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

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.

Set a webhook URL to receive notifications when visa applications are submitted

In your account settings, you can define a webhook URL to be notified whenever your agency submits a visa application. Each notification includes visa costs and who pays.

Account SettingsWebhook

Details

Where to set it

Log in to your dashboard and go to the 'Account Settings' tab. There you can add or update your webhook URL.

What it's used for

Your webhook will be triggered every time a visa application is submitted by your agency. The payload includes visa costs and whether the traveler/employee or the company/agency pays.

Payment information

paymentDetails includes the visa costs (government fee, service fee, processing-speed fee, and total) and who pays. paidBy is CLIENT when the traveler or employee pays, and AGENT when the company or agency pays. If YourVisa admin enables applicant-data sharing for your agency, the webhook also includes applicantDetails and time-limited download URLs for each file in applicantUploads. Those URLs expire after 5 minutes and work with a normal HTTPS GET from your server.

Example use

You might use this to sync applications with your internal CRM, send alerts, or perform custom logic on new submissions.

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": {}
}

Tips for Implementation

  • Always validate the parameters before constructing the URL to avoid errors.
  • Test your integration in a development environment before going live.
  • Keep your authentication credentials secure and never expose them in client-side code.
  • Contact support if you need assistance with implementation.