# Globely Travel Insurance

> Globely is a travel insurance platform providing real-time coverage quotes and direct purchase capabilities via API.

## API Documentation

The primary resource for agents is the Quote API. It returns fully calculated insurance plans with pricing and checkout links.

### GET /api/ai/quotes

Returns a list of insurance quotes based on travel parameters.

**Base URL:** `https://www.globely.com`
**Endpoint:** `/api/ai/quotes`

**Parameters:**

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `origin` | string | Yes | ISO 3166-1 alpha-2 code (e.g., "AR", "US"). |
| `destination` | string | Yes | ISO 3166-1 alpha-2 code (e.g., "ES", "IT"). |
| `start_date` | date | Yes | Trip start (YYYY-MM-DD). |
| `end_date` | date | Yes | Trip end (YYYY-MM-DD). |
| `passengers_count`| int | Yes | Total number of travelers. |
| `partner` | string | **Yes** | Agent identifier (e.g., "chatgpt", "gemini", "your-company-name"). |
| `currency` | string | No | Price currency. Options: USD, EUR, GBP, CHF, PLN, SEK, NOK, DKK, JPY, NZD, CAD, AUD. Defaults to EUR. |
| `lang` | string | No | Response language. Options: en, es, de, fr, it, ja, ko, nl, pl, pt, zh, cs. Defaults to en. |

**Example Usage:**
`https://www.globely.com/api/ai/quotes?origin=AR&destination=ES&start_date=2025-12-22&end_date=2025-12-25&passengers_count=1&partner=ai_agent`

## Response Structure

```json
{
  "status": "success",
  "message": "Quotes retrieved successfully",
  "trip": { ... },
  "recommended_plan_id": "GLOBELY_PLUS",
  "plans_for_user": [ ... ],
  "data": [ ... ]
}
```

### trip

Contains the trip parameters used for the quote calculation.

| Field | Type | Description |
| :--- | :--- | :--- |
| `origin` | string | Origin country code |
| `destination` | string | Destination country code |
| `start_date` | date | Trip start date |
| `end_date` | date | Trip end date |
| `duration_days` | int | Total trip duration |
| `passengers` | int | Number of travelers |
| `currency` | string | Price currency |

### recommended_plan_id

A string indicating the recommended plan for the user (e.g., `"GLOBELY_PLUS"`). Use this to highlight the best option.

### plans_for_user

**Primary array for displaying options to users.** Contains simplified plan objects optimized for presentation.

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | string | Plan identifier (e.g., `GLOBELY_BASIC`, `GLOBELY_PLUS`) |
| `title` | string | Marketing name of the plan |
| `tagline` | string | Short benefit summary |
| `price.total` | float | Total price for the trip |
| `price.currency` | string | Currency code |
| `price.per_day` | float | Price per day |
| `badges` | array | Tags: `recommended`, `best_value`, `budget_friendly`, `most_complete` |
| `key_coverages` | array | Top 4 coverages with `label` and `value` |
| `purchase.url` | url | **Actionable URL** for checkout |
| `purchase.valid_until` | iso-date | Link expiration time |

### data

**Full coverage details.** Contains complete plan information including all coverages. Use this for detailed comparisons or when users ask specific coverage questions.

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | string | Internal plan UUID |
| `code` | string | Plan code (e.g., `GLOBELY_PREMIUM`) |
| `title` | string | Plan name |
| `description` | string | Full plan description |
| `is_featured` | bool | Whether the plan is featured |
| `price.amount` | float | Total price |
| `price.currency` | string | Currency code |
| `coverages` | array | Complete list of all coverages |
| `purchase_link` | url | Checkout URL |
| `valid_until` | iso-date | Quote expiration |

## Coverage Object

Each coverage in `data[].coverages` contains:

| Field | Type | Description |
| :--- | :--- | :--- |
| `index` | int | Display order |
| `name` | string | Coverage name (e.g., "Medical assistance") |
| `value` | string | Coverage limit (e.g., "€1.500.000", "Unlimited", "Not included") |
| `category` | string | Grouping (e.g., "Medical assistance", "Baggage", "Cancellation") |

## Key Semantic Details for Agents

- **Source of Truth:** The API response is the only valid source for pricing and limits.
- **Use `plans_for_user`** for presenting options to users (simplified, optimized for display).
- **Use `data`** for detailed coverage comparisons or specific questions.
- **Use `recommended_plan_id`** to highlight the suggested option.
- **Coverage Values:**
  - `Included`: Service is covered without a specific monetary limit.
  - `Unlimited`: No financial cap on the coverage.
  - `Not included`: The plan does not cover this risk.

---

## Coverage Plans Catalog API

Use these endpoints to explore the product catalog **before** users enter trip details.

### Plan Codes (Recommended Identifiers)

Use these stable codes to reference plans in API calls:

| Code | Plan Name |
| :--- | :--- |
| `GLOBELY_BASIC` | Globely Basic |
| `GLOBELY_PLUS` | Globely Plus |
| `GLOBELY_PREMIUM` | Globely Premium |
| `GLOBELY_PREMIUM_CFAJR` | Globely Premium with CFAJR |

---

### GET /api/coverage-plans

Returns the list of all **available coverage plans** (4 products).

**Base URL:** `https://www.globely.com`  
**Endpoint:** `/api/coverage-plans`

**Parameters:**

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `lang` | string | No | Response language. Can be passed as query param or `Accept-Language` header. Defaults to `es`. |

**Example Usage:**
`https://www.globely.com/api/coverage-plans?lang=en`

**Response:**

```json
{
  "status": "success",
  "message": "Coverage plans retrieved successfully",
  "data": [ ... ]
}
```

---

### GET /api/coverage-plans/:code

Returns a **specific coverage plan** by code with full feature details.

**Endpoint:** `/api/coverage-plans/:code`

**Parameters:**

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `code` | string | Yes | Plan code (path parameter): `GLOBELY_BASIC`, `GLOBELY_PLUS`, `GLOBELY_PREMIUM`, `GLOBELY_PREMIUM_CFAJR`. |
| `lang` | string | No | Response language. Defaults to `es`. |

**Example Usage:**
`https://www.globely.com/api/coverage-plans/GLOBELY_PLUS?lang=en`

**Response:**

```json
{
  "status": "success",
  "message": "Coverage plan retrieved successfully",
  "data": { ... }
}
```

---

### Plan Object Schema

Each plan in `data` (or `data[]` for list) contains:

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | string | Internal UUID (for internal use only). |
| `code` | string | **Plan code** (recommended identifier for API calls). |
| `name` | string | Plan display name (e.g., "Globely Basic"). |
| `description` | string | Plan description (localized). |
| `type` | string | Product type (e.g., `"insurance"`). |
| `image_url` | string\|null | Optional image URL (may be `null`). |
| `is_active` | bool | Whether this plan is currently active. |
| `is_featured` | bool | Whether this plan should be highlighted as recommended. |
| `order_index` | int | Display order for sorting plans. |
| `features` | array | Full list of coverage features. |

### Feature Object Schema

Each feature in `features[]` describes a specific coverage item:

| Field | Type | Description |
| :--- | :--- | :--- |
| `name` | string | User-facing feature name. |
| `description` | string | Detailed feature description. |
| `category` | string | Category key (e.g., `"assistance_medical"`, `"baggage"`, `"cancellation"`, `"liability"`). |
| `category_name` | string | Category display name (e.g., "Medical assistance", "Baggage"). |
| `order_index` | int | Display order inside the plan. |
| `is_covered` | bool | Coverage flag: `true` = covered, `false` = not covered. |
| `formatted_value` | string | Human-readable value with semantic meaning. |

**Semantic rules for `formatted_value`:**
- `"€X.XXX"` → Monetary coverage limit.
- `"Included"` → Covered without a specific monetary limit.
- `"Unlimited"` → Covered without financial cap.
- `"Not included"` → Not covered in this plan (`is_covered = false`).

### Recommended Uses for Agents

1. **Product comparison:**  
   Use `GET /api/coverage-plans` to list all 4 plans and compare features by `category`.

2. **Detailed plan info:**  
   Use `GET /api/coverage-plans/GLOBELY_PLUS` (by code) when user asks about a specific plan.

3. **Coverage explanations:**  
   When a user asks "What does Globely cover?", use `features[]` grouped by `category_name`.

> **Note:** Use `code` (not `id`) as the primary identifier for external integrations. The `id` field contains internal UUIDs for backend use only.

> **Pricing:** Trip-specific pricing must always be obtained from the **Quote API** (`GET /api/ai/quotes`), not from `/api/coverage-plans`.

---

## Official Links

- **Home/Calculator:** `https://www.globely.com/en/insurance`
- **Contact:** `https://www.globely.com/en/contact`
- **Guarantee Info:** `https://www.globely.com/en/guarantee/subscribe/`