Overview
Get API access
API
Overview
Get API access
API

Get Products

GET /products

Retrieves a list of products with advanced filtering and consolidation options.

Request

Headers

x-api-key: YOUR_API_KEY_HERE

Query Parameters

Query
{
  status?: ProductStatus | "ALL"           // Filter by status (default: "ACTIVE")
  provider?: string                        // Filter by provider (default: "SHERPA")
  destination?: string                     // Filter by destination country (ISO 3-letter code)
  nationality?: string                     // Filter by nationality (ISO 3-letter code)
  subType?: EerType                        // Filter by EER type
  travelPurpose?: ProductTravelPurposeType // Filter by travel purpose
  currency?: string                        // Currency for pricing (default: "USD")
  language?: string                        // Language for localization (default: "en-US")
  consolidateProducts?: boolean            // Consolidate product variants (default: false)
  arrivalDate?: string                     // Arrival date (not implemented yet)
  residenceCountry?: string                // Residence country (not implemented yet)
  page?: number                           // Page number for pagination (default: 1)
  limit?: number                          // Items per page (default: 50, max: 100)
}

Example Requests

Get All Active Products

Get
curl --location 'https://api.joinsherpa.io/v2/products?status=ACTIVE' \
--header 'x-api-key: YOUR_API_KEY_HERE'

Filter by Destination and Nationality

Filter
curl --location 'https://api.joinsherpa.io/v2/products?destination=TUR&nationality=USA&currency=USD' \
--header 'x-api-key: YOUR_API_KEY_HERE'

Get Products with Consolidation

Get
curl --location 'https://api.joinsherpa.io/v2/products?consolidateProducts=true&destination=TUR' \
--header 'x-api-key: YOUR_API_KEY_HERE'

Filter by Travel Purpose

Filter
curl --location 'https://api.joinsherpa.io/v2/products?travelPurpose=TOURISM&destination=TUR' \
--header 'x-api-key: YOUR_API_KEY_HERE'

Response

Success Response (200 OK)

Products
[
  {
    "name": "Turkey eVisa",
    "shortName": "Turkey eVisa",
    "description": "Electronic visa for Turkey tourism and business travel",
    "programId": "turkey-evisa",
    "productId": "turkey-evisa-tourism",
    "status": "ACTIVE",
    "type": "visa",
    "subType": {
      "value": "E_VISA",
      "label": "Electronic Visa"
    },
    "provider": {
      "value": "SHERPA",
      "label": "Sherpa"
    },
    "numberOfEntries": {
      "value": "SINGLE",
      "label": "Single Entry"
    },
    "travelPurposes": [
      {
        "value": "TOURISM",
        "label": "Tourism"
      },
      {
        "value": "BUSINESS_VISITOR",
        "label": "Business Visitor"
      }
    ],
    "destinations": [
      {
        "value": "TUR",
        "label": "Turkey"
      }
    ],
    "eligibleNationalities": [
      {
        "value": "USA",
        "label": "United States"
      },
      {
        "value": "CAN",
        "label": "Canada"
      },
      {
        "value": "GBR",
        "label": "United Kingdom"
      }
    ],
    "pricing": {
      "price": 75.00,
      "currency": "USD",
      "breakdown": [
        {
          "type": "GOVERNMENT_FEE",
          "price": 50.00,
          "label": "Government Fee"
        },
        {
          "type": "APPLICATION_SERVICE_FEE",
          "price": 25.00,
          "label": "Application Service Fee"
        }
      ]
    },
    "validity": {
      "value": 180,
      "unit": "DAYS",
      "startsFrom": "APPROVAL",
      "label": "180 days from approval"
    },
    "processingTime": {
      "value": 24,
      "unit": "HOURS",
      "label": "24 hours"
    },
    "lengthOfStay": {
      "value": 90,
      "unit": "DAYS",
      "label": "90 days"
    }
  },
  {
    "name": "Turkey eTA",
    "shortName": "Turkey eTA",
    "description": "Electronic Travel Authorization for Turkey",
    "programId": "turkey-eta",
    "productId": "turkey-eta-tourism",
    "status": "ACTIVE",
    "type": "visa",
    "subType": {
      "value": "ETA",
      "label": "Electronic Travel Authorization"
    },
    "provider": {
      "value": "SHERPA",
      "label": "Sherpa"
    },
    "numberOfEntries": {
      "value": "MULTIPLE",
      "label": "Multiple Entry"
    },
    "travelPurposes": [
      {
        "value": "TOURISM",
        "label": "Tourism"
      }
    ],
    "destinations": [
      {
        "value": "TUR",
        "label": "Turkey"
      }
    ],
    "eligibleNationalities": [
      {
        "value": "USA",
        "label": "United States"
      }
    ],
    "pricing": {
      "price": 30.00,
      "currency": "USD",
      "breakdown": [
        {
          "type": "GOVERNMENT_FEE",
          "price": 30.00,
          "label": "Government Fee"
        }
      ]
    },
    "validity": {
      "value": 180,
      "unit": "DAYS",
      "startsFrom": "APPROVAL",
      "label": "180 days from approval"
    },
    "processingTime": {
      "value": 1,
      "unit": "HOURS",
      "label": "1 hour"
    }
  }
]

JavaScript Example

Get
const getProducts = async (filters = {}) => {
  try {
    // Build query parameters
    const params = new URLSearchParams();
    
    // Add filters
    if (filters.status) params.append('status', filters.status);
    if (filters.destination) params.append('destination', filters.destination);
    if (filters.nationality) params.append('nationality', filters.nationality);
    if (filters.subType) params.append('subType', filters.subType);
    if (filters.travelPurpose) params.append('travelPurpose', filters.travelPurpose);
    if (filters.currency) params.append('currency', filters.currency);
    if (filters.language) params.append('language', filters.language);
    if (filters.consolidateProducts !== undefined) {
      params.append('consolidateProducts', filters.consolidateProducts);
    }
    if (filters.page) params.append('page', filters.page);
    if (filters.limit) params.append('limit', filters.limit);

    const response = await fetch(`https://api.joinsherpa.io/v2/products?${params}`, {
      method: 'GET',
      headers: {
        'x-api-key': `${API_KEY}`,
      },
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API Error: ${errorData.message}`);
    }

    const products = await response.json();
    console.log('Products retrieved:', products);
    return products;
  } catch (error) {
    console.error('Error retrieving products:', error);
    throw error;
  }
};

// Usage examples
const examples = {
  // Get all active products
  getAllProducts: () => getProducts({ status: 'ACTIVE' }),
  
  // Get products for Turkey
  getTurkeyProducts: () => getProducts({ 
    destination: 'TUR', 
    status: 'ACTIVE' 
  }),
  
  // Get products for US citizens traveling to Turkey
  getUSATurkeyProducts: () => getProducts({ 
    destination: 'TUR', 
    nationality: 'USA',
    status: 'ACTIVE' 
  }),
  
  // Get tourism products for Turkey
  getTourismProducts: () => getProducts({ 
    destination: 'TUR', 
    travelPurpose: 'TOURISM',
    status: 'ACTIVE' 
  }),
  
  // Get consolidated products
  getConsolidatedProducts: () => getProducts({ 
    destination: 'TUR',
    consolidateProducts: true 
  }),
  
  // Get products with pagination
  getProductsWithPagination: (page = 1, limit = 10) => getProducts({ 
    page, 
    limit 
  })
};

// Example usage
examples.getTurkeyProducts().then(products => {
  console.log('Turkey products:', products);
});

Filtering Options

Status Filtering

  • ACTIVE - Only active products (default)
  • INACTIVE - Only inactive products
  • ALL - All products regardless of status

Destination Filtering

Use ISO 3-letter country codes:

  • TUR - Turkey
  • USA - United States
  • GBR - United Kingdom
  • CAN - Canada

Nationality Filtering

Use ISO 3-letter country codes for passport holders:

  • USA - US passport holders
  • GBR - UK passport holders
  • CAN - Canadian passport holders

SubType Filtering

  • E_VISA - Electronic Visa
  • ETA - Electronic Travel Authorization
  • E_TOURIST_CARD - Electronic Tourist Card
  • PAPER_VISA - Paper Visa

Travel Purpose Filtering

  • TOURISM - Tourism
  • BUSINESS_VISITOR - Business Visitor
  • TRANSIT - Transit
  • MEDICAL - Medical
  • MEDICAL_ATTENDANT - Medical Attendant
  • CONFERENCE - Conference
  • BUSINESS - Business
  • SHORT_TERM_STUDY - Short Term Study

Product Consolidation

When consolidateProducts=true, the API returns consolidated product variants:

  • One SHERPA product per destination
  • One GOVERNMENT product per destination
  • Variants are merged into single products
  • Useful for simplified product catalogs
💡 Consolidation Example

Instead of returning multiple Turkey eVisa variants (tourism, business, etc.), consolidation returns a single "Turkey eVisa" product that covers all travel purposes for that destination.

Pagination

For large product catalogs, use pagination:

// Get first page with 20 items
const products = await getProducts({ 
  page: 1, 
  limit: 20 
});

// Get next page
const nextPage = await getProducts({ 
  page: 2, 
  limit: 20 
});

Error Responses

400 Bad Request

{
  "errorCode": "INVALID_PARAMETERS",
  "message": "Invalid query parameters",
  "data": {
    "field": "destination",
    "reason": "Invalid country code"
  }
}

401 Unauthorized

{
  "errorCode": "UNAUTHORIZED",
  "message": "Missing or invalid authentication token"
}

403 Forbidden

{
  "errorCode": "INSUFFICIENT_PERMISSIONS",
  "message": "User does not have required permissions to view products"
}

Best Practices

Performance Optimization

  • Use specific filters to reduce response size
  • Implement client-side caching for frequently accessed data
  • Use pagination for large datasets
  • Cache responses according to cache headers (1 hour)

Filtering Strategy

  • Start with broad filters (destination, nationality)
  • Add specific filters (travel purpose, subType) as needed
  • Use consolidation for simplified product catalogs
  • Combine multiple filters for precise results

Error Handling

  • Always check HTTP status codes
  • Handle empty result sets gracefully
  • Implement retry logic for transient errors
  • Log errors for debugging and monitoring