Quote and Policy Search

The API exposes separate search families for pre-purchase quotes and issued policies:

Do not use saved-quote operations to service an issued policy. Do not treat a saved quote as proof of current price or product availability.

Search Design

Run searches from your backend and enforce object-level authorization before returning results. Agency number, quote number, plan number, transaction ID, names, email, phone, dates, and ZIP code are untrusted identifiers, not authorization evidence.

Prefer the narrowest known identifier:

1. Use quoteNumber for a known quote.
2. Use planNumber for a known issued policy.
3. Use transactionId with searchPlan when tracing issued policies related to a known payment transaction.
4. Combine agency and customer attributes when the direct identifier is unknown.
5. Return a selection screen when multiple records match; do not guess which record belongs to the user.

Find Saved Quotes

Request

query SearchSavedQuotes(
  $quoteSearchRequest: QuoteSearchRequestInput!
  $first: Int
  $after: String
  $last: Int
  $before: String
) {
  searchSavedQuotes(
    quoteSearchRequest: $quoteSearchRequest
    first: $first
    after: $after
    last: $last
    before: $before
  ) {
    totalCount
    nodes {
      quoteNumber
      isAnnualQuote
      planNumber
      createDate
      departureDate
      returnDate
      agencyNumber
      agencyName
      advisorName
      residencyCountryIsoCode
      residencyStateIsoCode
      destinations {
        countryIsoCode
        destinationName
      }
      travelers {
        firstName
        lastName
        email
        isPrimary
        tripCost
      }
    }
    edges {
      cursor
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Request example variables:

{
  "quoteSearchRequest": {
    "agencyNumber": "<authorized-agency-number>",
    "email": "<customer-email>"
  },
  "first": 20,
  "after": null
}

Quote Search Filters

Every field in QuoteSearchRequestInput is optional, but the request object itself is required.

Text matching and multi-filter behavior can vary by environment configuration. Do not present exact, partial, or case-sensitive matching as a user-facing guarantee unless that behavior is defined in your account contract and covered by representative tests.

Result Interpretation

• isAnnualQuote tells you which quote mutation to use when refreshing the quote.
• planNumber can indicate that a saved quote record is associated with an issued policy. Use searchPlan for policy servicing.
• totalCount is the count reported by the connection, not the number of nodes in the current page.
• Request only fields required by the current screen. Traveler and trip fields contain personal data.

Load One Saved Quote

After the user selects a quote, retrieve its stored input context by quote number.

query GetSavedQuote($quoteNumber: String!) {
  savedQuote(quoteNumber: $quoteNumber) {
    quoteNumber
    isAnnualQuote
    quoteInput {
      agencyNumber
      agentId
      applicationDate
      residencyCountryIsoCode
      residencyStateIsoCode
      tripType
      trip {
        departureDate
        depositDate
        returnDate
        destinations {
          countryIsoCode
          stateIsoCode
          destinationId
          destinationName
        }
        travelers {
          id
          primaryTraveler
          firstName
          lastName
          email
          dateOfBirth
          tripCost
        }
      }
    }
    annualQuoteInput {
      agencyNumber
      agentId
      applicationDate
      effectiveDate
      residencyCountryIsoCode
      residencyStateIsoCode
      tripType
      travelers {
        id
        primaryTraveler
        firstName
        lastName
        email
        dateOfBirth
      }
      tripSegment {
        departureDate
        depositDate
        returnDate
        destinations {
          countryIsoCode
          stateIsoCode
          destinationId
          destinationName
        }
        travelers {
          id
          firstName
          lastName
          dateOfBirth
          tripCost
        }
      }
    }
    quoteReminders {
      first
      second
      third
    }
  }
}

Request example variables:

{
  "quoteNumber": "<saved-quote-number>"
}

Use isAnnualQuote to choose the applicable branch:

• false: use quoteInput to prefill the single-trip experience.
• true: use annualQuoteInput to prefill the annual experience.

Treat nullable branches as absent rather than manufacturing defaults. A saved quote is resumable input context, not a guaranteed current offer.

The query now retrieves the SDL-exposed dates, destinations, travelers, costs, primary-traveler flag, annual traveler configuration, and optional annual trip segment needed to prefill the documented review experience. Product selections and current prices are not exposed by SavedQuoteResults; refresh them with the applicable quote mutation before purchase or staging.

Resume and Re-Quote

Single-Trip Quote

1. Load savedQuote.
2. Prefill the form from quoteInput.
3. Let the customer confirm or update dates, destinations, travelers, and costs.
4. Call quote with the complete confirmed input.
5. Replace the stored checkout quote number with the new response quoteNumber.
6. Select products and coverage IDs only from the new response.

The saved quote number identifies the stored record. After requoting, treat the new quoteNumber, products, coverage IDs, and prices as authoritative; do not continue with selections from the older quote.

See Single Trip Quote & Purchase for the quote selection and purchase handoffs.

Annual Quote

1. Load savedQuote and verify isAnnualQuote is true.
2. Prefill from annualQuoteInput.
3. Keep traveler IDs stable while the customer reviews travelers and optional trip-segment data.
4. Call annualPlanQuote with the complete confirmed input.
5. Replace the earlier quote number and product selection with the new response.

Keep traveler IDs associated with the same people while editing the resumed form. After requoting, the new quote number and returned product state replace the saved pricing context.

See Annual Plan Quote & Purchase.

Find Issued Policies

searchPlan returns detailed issued-plan records. Because its nodes can include traveler, payment, claim, document, history, and pricing data, request only fields needed for the authorized workflow.

Request

query SearchPlans(
  $planSearchRequest: PlanSearchRequestInput!
  $first: Int
  $after: String
  $last: Int
  $before: String
) {
  searchPlan(
    planSearchRequest: $planSearchRequest
    first: $first
    after: $after
    last: $last
    before: $before
  ) {
    totalCount
    nodes {
      planNumber
      planStatus
      planType
      isActive
      isAnnual
      issueDate
      effectiveDate
      expirationDate
      source
      planPrimaryTraveler {
        firstName
        lastName
      }
      planProduct {
        productCode
        productName
      }
      planTripDetails {
        departureDate
        returnDate
      }
      segmentTripDetails {
        policySegmentGuid
        departureDate
        returnDate
        isModifyEnabled
      }
      planDocuments {
        documentType
        downloadLink
      }
    }
    edges {
      cursor
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

The following example looks up an issued policy by plan number.

Request example variables:

{
  "planSearchRequest": {
    "agencyNumber": "<authorized-agency-number>",
    "planNumber": "<issued-plan-number>",
    "searchAllTravelers": false
  },
  "first": 10,
  "after": null
}

Policy Search Filters

searchAllTravelers is the only required field inside PlanSearchRequestInput.

Transaction-based policy lookup is supported only by searchPlan. It is not a filter for searchSavedQuotes or savedQuote. A matching transaction identifies candidate issued policies but does not establish that the caller is authorized to view or service them.

Use searchAllTravelers, strictSearch, filterBy, and isSortBy only when their allowed values and semantics are defined in your account contract. Do not expose guessed labels or behavior in a production UI; test representative records before release.

Choose Result Fields by Workflow

Do not return full plan nodes to every client merely because the schema permits it.

Cursor Pagination

Both search operations support Relay-style forward and backward pagination.

Forward

1. Send first with no after for the first page.
2. Read pageInfo.hasNextPage.
3. When true, send the prior pageInfo.endCursor as after.

{
  "first": 20,
  "after": "<previous-end-cursor>"
}

Backward

1. Send last and a known before cursor.
2. Read pageInfo.hasPreviousPage.
3. Use pageInfo.startCursor as the next before value when moving backward.

Do not send both pagination directions for one navigation action. Cursors are opaque: store and replay them exactly, and do not parse or construct them. Use the default and maximum page sizes assigned to your environment.

No Results, Multiple Results, and Errors

• No results: allow the user to verify inputs; do not reveal whether an unauthorized record exists.
• Multiple results: show the minimum attributes needed to choose safely, then load the selected record.
• Invalid cursor: restart from the first page rather than editing the cursor.
• Unauthorized scope: fail closed and log a non-sensitive audit event.
• Transient API failure: retry reads with bounded backoff; do not broaden filters automatically.

Security and Privacy

• Authorize every quote or policy object after search and before detail display.
• Restrict transaction, claim, payment, and document fields by support role and business purpose.
• Mask names, emails, phone numbers, addresses, dates of birth, and transaction IDs in logs.
• Do not place production identifiers or personal data in URLs, analytics events, screenshots, or sample payloads.
• Apply rate limits and monitoring to customer-enumeration search paths.

Related Guides

• Single Trip Quote & Purchase
• Annual Plan Quote & Purchase
• Single Trip Modification
• Annual Plan Modification