Getting Started

Welcome to the Embrace API integration guide. This Getting Started page gives you an end‑to‑end map of the core documents you’ll use to quote, validate user input, and complete a purchase—either via hosted redirect (Quote Engine) or embedded Stripe checkout.

Make sure to review the Prerequisites page first (API keys, environment, basic tooling).

Integration Journey Overview

Phase Goal Primary Doc Key Endpoints / Artifacts
1. Collect Inputs Gather contact & pet data Quoting POST /v2/quotes/fullquote
2. (Optional) Validate Pre‑validate address, name, phone Validation POST /v2/validation/address
POST /v2/validation/name
POST /v2/validation/phone
3. Refine Quote Add / remove pets, adjust coverage or frequency Quoting Updates POST /v2/quotes/fullquote (full replace)
POST /v2/quotes/fullquote/{quoteId}/pet
PUT /v2/quotes/fullquote/{quoteId}/pet
PUT /v2/quotes/{quoteId}/contact
4. Choose Purchase Path Redirect (minimal) or Embedded Stripe (custom UX) Purchase Redirect: quoteLinkUrl
Stripe: POST /v2/quotes/{quoteId}/checkout
5. Complete Purchase Finalize policy (Stripe path) Purchase POST /v2/quotes/fullquote/{quoteId}/purchase-stripe

Why Two Purchase Paths?

  • Redirect (Quote Engine): Fastest integration—obtain quoteLinkUrl from quote response and send the user to Embrace’s hosted experience.
  • Stripe Embedded: Keep users on your site; you manage checkout UI using Stripe Elements then finalize via Embrace purchase endpoint.

Use the Purchase page to compare both and implement the one that aligns with your UX and timeline.

Updating Quotes After Initial Request

All changes can be expressed as a full re‑POST of the quote. For targeted operations use:

  • Add pet: POST /v2/quotes/fullquote/{quoteId}/pet
  • Update single pet: PUT /v2/quotes/fullquote/{quoteId}/pet
  • Change payment frequency only: PUT /v2/quotes/{quoteId}/contact

See the update sections in Quoting for examples & replacement semantics.

Validation Shortcuts

Improve form UX and reduce quote failures by calling:

  • Address: POST /v2/validation/address
  • Name: POST /v2/validation/name
  • Phone: POST /v2/validation/phone

Details and response formats: Validation

Purchase Flow (Embedded Stripe Summary)

  1. Quote (get quoteId)
  2. Checkout: POST /v2/quotes/{quoteId}/checkout → Stripe keys
  3. Initialize Stripe Elements & collect payment method (no auto redirect with redirect: 'if_required')
  4. Purchase: POST /v2/quotes/fullquote/{quoteId}/purchase-stripe → purchaseSucceeded, policyNumber

Redirect Flow Summary

  1. Quote → capture premiumSummary.quoteLinkUrl
  2. (Optional) add a pet via pet endpoint
  3. Redirect user to quoteLinkUrl (policy purchased on hosted experience)

Where to Go Next