API Integration Guide

Intended Audience: Partner development teams and technology executives
Last Updated: August 18, 2026
Version: 3.0

This guide consolidates the current partner integration surface into a single reference for single-trip and annual-plan workflows.

It is aligned to the partner-ready Postman and Insomnia collections available for download above. Those collections cover quoting, staged purchase, payment handoff, policy binding, quote search, plan search, single-trip servicing, and annual-plan servicing.

For visual request sequences, see the Single Trip Quote to Purchase Flow and Annual Plan Quote to Purchase Flow.

Overview

Travel Insured's GraphQL API supports two policy models:

• Single Trip policies for one-trip travel
• Annual Plan policies for recurring or multi-trip annual coverage

The current partner collections support these workflows:

Collections To Use

Use the partner-ready collections available for download on this page:

• Postman collection — TravelInsured.partner.postman_collection.json
• Insomnia collection — TravelInsured.partner.insomnia.yaml

1. Authentication and Environment Setup

Every request must include:

• Authorization: ApiKey {{apiToken}}
• x-api-key: {{apiKey}}
• Content-Type: application/json

Send the API token exactly as an ApiKey header value. Do not use a Bearer prefix.

Required Environment Values

Set these values before running transactional requests:

Annual Flow Variables

The unified collection also includes annual-plan placeholders that should be set to valid future dates in the target environment:

Servicing Variables

The collection stores or expects these values during policy servicing:

2. Core State Across the Flow

Persist and pass these identifiers unchanged between requests:

3. Workflow Map

The unified collection is organized into these folders:

Start with Test GraphQL Connectivity before any transactional request.

4. Single-Trip Quote and Purchase

Supported Purchase Patterns

Single-trip policies support both purchase patterns in the broader API surface:

1. Streamlined purchase using purchasePolicy
2. Deferred purchase using stagePolicyPurchase, processPayment, and policyBindRequest

The updated partner collections center the deferred flow and related servicing operations.

Step 1: Generate Quote

Use quote to retrieve:

• quoteNumber
• available products
• optional coverage IDs
• accepted payment methods

Use the returned products to drive product selection rather than hardcoding product or coverage values.

Step 2: Stage Policy Purchase

Use stagePolicyPurchase with the selected productCode, traveler details, trip details, and delivery preferences.

Retain:

• planGuid

Step 3: Process Payment

Use processPayment with:

• planGuid
• paymentMethod
• optional billing or hosted-payment configuration

Retain:

• paymentRequestId
• planGuid

Step 4: Bind the Policy

Use policyBindRequest with:

• planGuid
• confirmed transactionId

Retain:

• planNumber
• policy document links

Streamlined Purchase Note

If your checkout can submit payment directly inside the purchase mutation, purchasePolicy remains a valid single-trip pattern. Persist the returned policyNumber as the final issued policy identifier for that path.

5. Annual Quote and Purchase

Annual purchase uses annual-specific quote and staging mutations, then reuses the same deferred payment and policy-binding steps.

Step 1: Annual Plan Quote

Use annualPlanQuote with:

• agencyNumber
• effectiveDate
• residency country and state
• annual travelers
• optional tripSegment

Retain:

• quoteNumber
• annual productCode
• selected optional coverage identifiers

Implementation guidance from the updated collection behavior:

1. Set annualEffectiveDate to today or later in the target environment.
2. Use annual product codes returned by annualPlanQuote; do not reuse single-trip product codes.
3. If you include tripSegment, keep the dates and traveler IDs consistent between quote and staging.

Step 2: Stage Annual Policy Purchase

Use stageAnnualPolicyPurchase with:

• quoteNumber
• agencyNumber
• deliveryTypes[]
• planTravelers[]
• product.productCode
• optional product.effectiveDate
• optional tripSegment

Retain:

• planGuid

Implementation guidance from live validation:

1. Keep traveler IDs stable between annual quote and annual staging.
2. Include contactInfo for the primary traveler even though it is nullable in schema.
3. Include product.effectiveDate when staging annual plans. The sandbox implementation expects it.

Step 3: Process Payment

Use the shared processPayment mutation with the staged annual planGuid.

Step 4: Bind the Annual Policy

Use the shared policyBindRequest mutation with:

• planGuid
• confirmed transactionId

Retain:

• planNumber
• policy document links

6. Search, Resume, and Requote

Use folder 03 - Quote Search and Requote when you need to resume or refresh quote data.

Available capabilities:

• searchSavedQuotes
• savedQuote
• single-trip re-quote using quote
• annual re-quote using annualPlanQuote

The partner collection models quote modification as re-quoting. Do not assume there is a separate partner-safe modifyQuote mutation.

7. Plan Search and Policy Servicing

Use searchPlan before servicing or modification when you need the issued policy context.

The updated collection uses searchPlan to return:

• planNumber
• policy status and type
• primary traveler details
• available plan coverages
• annual segment identifiers needed for annual servicing

For annual-plan servicing specifically, searchPlan is the source for the live traveler and segment identifiers required by downstream annual modification requests.

8. Single-Trip Plan Modification

Use this sequence for issued single-trip policies:

1. searchPlan
2. planModificationQuote
3. planModifyRequest
4. processPayment only if the modification increases cost
5. planModify

Retain:

• modificationPlanGuid

If no payment is required, finalize through planModify without inventing a separate payment step.

9. Annual Plan Modification

Use this sequence for issued annual policies:

1. searchPlan
2. annualPlanModificationQuote
3. annualPlanModifyRequest
4. processPayment only if the modification increases cost
5. planModify

Annual Modification Requirements

Annual servicing has a few operational requirements that should be called out explicitly:

1. Use searchPlan first to obtain the current annual traveler ID and current annual segment ID.
2. Populate tripSegment.tripId from the current policy segment you are updating.
3. Include depositDate on annual trip-segment modification requests.
4. Select productCoverageLimitId and productCoverageTypeCode from the annual modification quote response rather than hardcoding them.
5. Use shared planModify for finalization after payment when the change increases cost.

The updated partner collections include dedicated environment variables for these annual modification values so the workflow can be executed directly after searchPlan and the pricing step.

10. Payment Handling Notes

The partner-safe collections are designed around deferred payment orchestration.

• processPayment does not carry raw payment card data in the example payloads.
• hostedPaymentUrl and iFrameCommunicatorUrl should be partner-owned URLs.
• The final bind or modification finalization step should only run after a confirmed payment result yields a valid transactionId.

11. Failure Handling and Validation Tips

If a request fails:

1. Re-run Test GraphQL Connectivity.
2. Confirm graphqlBaseUrl, apiToken, and apiKey are set correctly.
3. Confirm stored flow identifiers came from the same environment and the current session.
4. Use only product codes and coverage IDs returned by quote or modification quote responses.
5. For annual requests, confirm the effective date is current and that annual modification requests include depositDate plus live traveler and trip identifiers.

12. Best Practices

1. Treat quote references as resumable pricing context, not guaranteed price locks.
2. Persist planNumber or policyNumber as the final system-of-record identifier.
3. Keep staging and payment state session-scoped.
4. Do not commit live credentials, production endpoints, or customer data into source control.
5. When you need a capability outside the allowlisted partner collections, request a reviewed update rather than copying requests from the raw export.

13. Next Steps

1. Import the unified partner collection and environment.
2. Validate connectivity through Test GraphQL Connectivity.
3. Test the single-trip deferred flow end to end.
4. Test the annual deferred flow end to end.
5. Validate quote resume, plan search, and both servicing paths before production cutover.