API Integration Guide

Use this page to choose a workflow and understand the contracts shared across Travel Insured partner integrations. Each linked workflow guide is the canonical source for operation order, request examples, carry-forward fields, and recovery behavior.

Authentication

Send every GraphQL request over TLS with these headers:

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

Keep both credentials in an approved server-side secret store. Do not use a Bearer prefix, place credentials in URLs, or include them in logs, source control, client bundles, analytics, or support screenshots. Coordinate environment setup, credential issuance, and rotation through your Travel Insured Account Manager.

Shared Contract Rules

• Treat GraphQL non-null markers (!) as schema requiredness. Business validation can impose additional constraints not represented by the SDL.
• Treat identifiers, customer fields, browser events, and model responses as untrusted input.
• Use product codes, coverage type codes, coverage limit IDs, traveler IDs, and segment IDs returned by the current environment. Do not invent or copy them across environments.
• Requote after a pricing input changes. The latest quote number, products, coverage choices, and totals replace earlier pricing state.
• Keep planGuid, payment-session state, and modificationPlanGuid in server-side checkout state. Persist planNumber as the issued policy identifier.
• Authorize every quote, policy, payment, and document action on the backend. A matching identifier is not authorization evidence.
• Use the approved payment path once per intended transaction. Reconcile an unknown outcome before retrying or collecting payment again.

Workflow Matrix

Single-trip purchase and modification support direct AR or approved provider-token operations when enabled for the partner account. The published schema does not expose equivalent annual direct operations. Do not submit annual request shapes to single-trip mutations.

Canonical Workflow Guides

Single Trip Quote & Purchase

Quote a single trip and choose either the enabled direct purchase path or deferred staging with hosted payment.

Annual Plan Quote & Purchase

Quote annual coverage, optionally include a known trip segment, stage the annual policy, and complete hosted payment.

Quote and Policy Search

Search saved quotes, restore resumable input, re-quote current pricing, find issued policies, and paginate results safely.

Search Examples

Use ten purpose-built searchPlan examples for policy lookup, reconciliation, traveler and date searches, annual servicing, and authorized support workflows.

Single Trip Modification

Authorize an issued policy, quote a proposed change, and choose the additional-payment, enabled no-payment, or direct refund path from totalAmountDue. A negative quote uses entitled modifyPlan with AR or an approved provider token.

Annual Plan Modification

Retrieve annual traveler and segment identifiers, quote an annual change, and choose the amount-driven completion path. A negative quote requires the annual-capable direct operation assigned during onboarding; the public SDL does not name that operation.

Modification refunds are not cancellations. The public schema does not expose a general paid retail cancellation mutation, and a modification must not be used as a cancellation workaround.

Payment Boundary

The hosted PCI form, not the partner application, captures card data. Browser callbacks are UX signals and do not prove payment or binding success. Confirm the authoritative result through the payment-session status endpoint from the partner backend before displaying final success or releasing policy documents.

Only a status response with status: "Bound" and bindStatus: "Bound" confirms completion and supplies the trusted planNumber and available document links. The verified embedded-payment contract is for staged purchases; use only a separately approved contract for policy modifications or refunds.

Operational Baseline

• Classify failures using Error Handling.
• Retry only eligible operations according to Retries & Idempotency.
• Bound concurrency and honor service signals described in Rate Limits.
• Mask credentials, customer data, quote and policy identifiers, payment state, and document links in logs.
• Test positive, negative, authorization, tenant-isolation, duplicate-submission, timeout, and uncertain-payment scenarios before production release.