Integrate with the API

The end-to-end path for a custom storefront or back office: list categories, get quotes, show the offer, create contracts when the order is paid, report fulfilment, update or cancel, and look contracts up.

This page walks one order through the SureBright API, from the first quote to a cancelled plan. It is for teams selling from their own storefront, app or back office rather than through one of SureBright's platform integrations.

Each step names the endpoint, shows a minimal request and lists the response fields the next step needs. The linked reference pages carry the full field lists.

Before you start#

You need the API host (HOST_NAME), your storeId and an API key. Authentication says where each comes from. The category and quote calls in steps 1 to 3 take no key. Make the Order calls from your server, never from the browser, so the key stays private.

While you build, keep "isTestOrder": true in the order body in step 4. The order is recorded as a test order with a Test badge on Sales. See Live keys and testing.

The integration, step by step#

  1. Get your store's categories

    List Category: GET /quote/api/storeCategory/listStoreCategories

    bash
    curl 'https://{HOST_NAME}/quote/api/storeCategory/listStoreCategories?storeId={storeId}'

    The response is an array. From each entry keep:

    FieldUse
    sbCategoryIdThe category to quote against in step 2
    sbCategoryName, labelListNames for mapping your product types to a category
    storeParentIdSent with sbCategoryId in step 2

    If your store uses the category tree, the same endpoint returns one level per call, or every priced leaf with view=leaves. The reference page explains both.

  2. Get quotes for a product

    By Category: GET /quote/api/quote/category/listQuotes

    All inputs go in one JSON object, sent Base64-encoded as the payload query parameter. Send quoteSyncMode=SYNC so the quote is saved before the response returns and can be used in step 4 straight away.

    bash
    PAYLOAD=$(printf '%s' '{
      "storeParentId": "{storeParentId}",
      "country": "US",
      "visitId": "3d99a4ae-5cf0-4d87-8436-46c0cdc03676",
      "platform": "OFFLINE_PORTAL",
      "storeCategoryList": [
        { "sbCategoryId": "{sbCategoryId}", "productPrice": 199.99 }
      ]
    }' | base64 | tr -d '\n')
    
    curl -G 'https://{HOST_NAME}/quote/api/quote/category/listQuotes' \
      --data-urlencode 'quoteSyncMode=SYNC' \
      --data-urlencode "payload=${PAYLOAD}"

    country, visitId, platform and a non-empty storeCategoryList are required, and storeParentId must be present when you quote by sbCategoryId. visitId is any identifier you generate for the shopper's session. Add province when you know the shopper's state or province. Each storeCategoryList entry quotes one product.

    From quoteList[] keep:

    FieldUse
    quoteIdThe quote. Sent in step 4
    quoteItemList[].quoteItemIdOne plan option. Sent in step 4
    quoteItemList[].policyPrice, coverageYearsThe plan's price and term
    coverageListCoverage text to show beside the plans

    An empty quoteList means no plan matched that category and price. Show no offer.

    To quote by your own product and variant ids instead, see By Product. It only works for products SureBright already knows.

  3. Show the offer and let the shopper pick

    There is no API call in this step. Render one option per quoteItemList entry with its term and price, plus a way to decline. When the shopper picks a plan, store its quoteId, quoteItemId and price on your cart line.

    To read a saved quote back later, use Get a quote. When you render the offer yourself, post shopper interactions to the Event Collector if you want them in Sales analytics. If you would rather not build the offer UI, see Headless and custom storefronts.

  4. Create the contracts when the order is paid

    Create Contracts for Order: POST /partner/api/v1/order

    Call this once payment has succeeded. Contracts are created as soon as the request is accepted. If the request times out, send it again with the same orderId; see Limits, idempotency and versioning.

    bash
    curl -X POST 'https://{HOST_NAME}/partner/api/v1/order' \
      -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "storeId": "{storeId}",
        "orderId": "ORDER-1001",
        "orderPurchaseDate": "2026-11-12T10:15:30Z",
        "orderLineItemList": [
          {
            "lineItemId": "LINE-1",
            "productId": "PROD-1",
            "productSKU": "SKU-1",
            "productTitle": "Sample product",
            "quantity": 1,
            "salePrice": 199.99,
            "totalPrice": 199.99,
            "planDetails": {
              "policyPurchaseDate": "2026-11-12T10:15:30Z",
              "quoteId": "{quoteId}",
              "quoteItemId": "{quoteItemId}"
            }
          }
        ],
        "customerDetails": {
          "firstName": "Test",
          "lastName": "Customer",
          "customerEmail": "test.customer@example.com",
          "addressLine1": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "country": "US",
          "zipCode": "78701"
        },
        "isTestOrder": true
      }'

    What the request must carry:

    PartRequired fields
    OrderstoreId, orderId (your own order id), orderPurchaseDate, a non-empty orderLineItemList, customerDetails
    Each linelineItemId, productId, productSKU, productTitle, quantity, salePrice
    planDetailspolicyPurchaseDate, plus quoteId and quoteItemId from step 2
    customerDetailsfirstName, lastName, customerEmail, addressLine1, city, state, country, and zipCode or pinCode

    Dates are ISO 8601 with Z or a timezone offset. Put planDetails only on the lines that carry a plan; a line without it creates nothing. One contract is created per unit of quantity.

    In the response, contractList[] has one entry per contract (lineItemId, contractId, isCancelled). Store each contractId against your order line. errorList[] is present when something failed.

    200 means no line failed. 207 means some contracts were created and some lines failed. 400 means nothing was created. SureBright emails the customer the plan confirmation; see Emails your customers receive.

  5. Report fulfilment (only if coverage starts at shipment)

    Set or revert fulfillment dates: POST /order/api/v1/contract/fulfillment

    Skip this step unless your store is set up so that coverage starts when the product ships. The endpoint is enabled per store by SureBright and uses its own server-to-server token, not your API key. Ask your SureBright contact before you build it.

    bash
    curl -X POST 'https://{HOST_NAME}/order/api/v1/contract/fulfillment' \
      -H 'Authorization: Bearer {SERVICE_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "contractIds": ["{contractId}"],
        "action": "SET",
        "fulfillmentDate": "2026-11-14T09:00:00Z"
      }'

    Check results[]: each entry carries the contractId, its effectiveDate and expirationDate, and skipped: true when the contract already had dates. "action": "REVERT" clears the dates after a cancelled shipment.

  6. Update or cancel

    Cancel / Update contracts for Order: PUT /partner/api/v1/order

    Send the whole order again with the same orderId, changed to how it stands now. The body has the same shape and required fields as step 4; it is not a partial update.

    Change in your orderWhat to sendResult
    Fewer units of a covered productThe line with the lower quantityThe difference is cancelled
    The plan is removed or refundedThe line with quantity set to 0, or without planDetailsEvery contract on that line is cancelled
    More units of a covered productThe line with the higher quantityContracts are created for the extra units

    To cancel a whole order, do this for every plan line. Keep productId and optionId the same as in step 4, because a line's existing contracts are found by them. Cancelled contracts come back in contractList with isCancelled: true and cannot be reactivated. The customer receives a cancellation email.

  7. Look contracts up

    Get Contracts for Order: GET /partner/api/v1/order

    bash
    curl -G 'https://{HOST_NAME}/partner/api/v1/order' \
      --data-urlencode 'storeId={storeId}' \
      --data-urlencode 'partnerOrderId=ORDER-1001' \
      -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY'

    partnerOrderId is the orderId you sent in step 4. data.order is the order as SureBright stored it and data.contracts lists its active contracts; cancelled contracts are left out. A 404 with errorCode: ORDER_NOT_FOUND means there is no order with that id on that store.

    The lookup is one order per call. To see all contracts for a period, use the export on Sales.

Where claims are filed#

There is no claims step to build: the API has no claim endpoints. Customers file a claim in the customer portal or by email, as described in Filing a claim.