Briza OAS SDK

A toolkit for P&C insurance carrier integrations, providing a normalized interface to carrier quoting APIs, including datapoints/questions and classes.

Installation

npm install @briza/oas-sdk

Integration Guide

This step-by-step guide will help you integrate your application with carrier APIs using the SDK. The guide outlines the essential steps and offers three different integration flows in Step 3, allowing you to choose the approach that best fits your application's needs:

• Flow 1: Process all data points yourself (complete control)
• Flow 2: Use possible data points with your own conditional logic
• Flow 3: Let the SDK manage active data points based on conditions

┌────────────────┐     ┌─────────────┐     ┌───────────────────────────────────────────────────────┐
│ Step 1:        │     │ Step 2:     │     │ Step 3: Collect Data Points                           │
│ Classification ├────>│ Initialize  ├────>│ Choose one or more of the following flows:            │
└────────────────┘     │ Payload     │     │                                                       │
                       │ Builder     │     │ ┌─────────────┐    ┌─────────────┐    ┌─────────────┐ │
                       └─────────────┘     │ │ Flow 1      │    │ Flow 2      │    │ Flow 3      │ │
                                           │ │ All         │    │ Possible    │    │ Active      │ │
                                           │ │ Data Points │    │ Data Points │    │ Data Points │ │
                                           │ └──────┬──────┘    └──────┬──────┘    └─────┬───────┘ │
                                           └────────┼──────────────────┼─────────────────┼─────────┘
                                                    │                  │                 │
                                                    ▼                  ▼                 ▼
                                                  ┌─────────────────────────────────────────┐
                                                  │ Answer Collection (Your Implementation) │
                                                  └─────────────────────┬───────────────────┘
                                                                        │
                                                                        ▼
┌─────────────┐      ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│ Process     │      │ Step 5:     │       │ Valid       │       │ Step 4:     │
│ Normalized  │<─────┤ Submit      │<──────┤ Payload?    │<──────┤ Build       │
│ Response    │      │ Quote       │   Yes │             │       │ Quote       │
│             │      │ Request     │       │             │       │ Payload     │
└─────────────┘      └─────────────┘       └───────┬─────┘       └─────────────┘
                                                ▲  │ No
                                                │  │
                                                │  ▼
                                           ┌────┴────────┐
                                           │ Fix Errors  │
                                           └─────────────┘

Step 1: Classification

[
  {
    "code": "23814000_47205100_00000000",
    "title": "Masonry work",
    "properties": {
      "naics": [
        {
          "code": "238140",
          "description": "Brick veneer, installation"
        },
        {
          "code": "238140",
          "description": "Stonework (i.e., masonry) contractors"
        },
        {
          "code": "238140",
          "description": "Tuck pointing contractors"
        }
      ],
      "industry": "Small Contractors"
    },
    "states": [
      {
        "code": "AL",
        "name": "Alabama",
        "products": [
          {
            "code": "gl"
          }
        ]
      },
      {
        "code": "AR",
        "name": "Arkansas",
        "products": [
          {
            "code": "gl"
          }
        ]
      }
    ]
  },
  {
    "code": "23815000_47212100_01000000",
    "title": "Glass installation and repair (no auto work)",
    "properties": {
      "naics": [
        {
          "code": "238150",
          "description": "Curtain wall, glass, installation"
        }
      ],
      "industry": "Small Contractors"
    },
    "states": [
      {
        "code": "WI",
        "name": "Wisconsin",
        "products": [
          {
            "code": "gl"
          }
        ]
      },
      {
        "code": "WV",
        "name": "West Virginia",
        "products": [
          {
            "code": "gl"
          }
        ]
      },
      {
        "code": "WY",
        "name": "Wyoming",
        "products": [
          {
            "code": "gl"
          }
        ]
      }
    ]
  },
  {
    "code": "23821000_47211100_01000100",
    "title": "Electrical work (interior only)",
    "properties": {
      "naics": [
        {
          "code": "238210",
          "description": "Electric contracting"
        }
      ],
      "industry": "Small Contractors"
    },
    "states": [
      {
        "code": "AL",
        "name": "Alabama",
        "products": [
          {
            "code": "gl"
          }
        ]
      }
    ]
  }
]

[
  {
    "code": "0005",
    "title": "Farm - Nursery Employees & Drivers",
    "properties": {
      "ncci": "0005"
    },
    "states": [
      {
        "code": "AK",
        "name": "Alaska",
        "products": [
          {
            "code": "wc"
          }
        ]
      },
      {
        "code": "AL",
        "name": "Alabama",
        "products": [
          {
            "code": "wc"
          }
        ]
      }
    ]
  },
  {
    "code": "0012",
    "title": "Paid Furloughed Employees",
    "properties": {
      "ncci": "0012"
    },
    "states": [
      {
        "code": "CA",
        "name": "California",
        "products": [
          {
            "code": "wc"
          }
        ]
      },
      {
        "code": "FL",
        "name": "Florida",
        "products": [
          {
            "code": "wc"
          }
        ]
      },
      {
        "code": "MA",
        "name": "Massachusetts",
        "products": [
          {
            "code": "wc"
          }
        ]
      }
    ]
  },
  {
    "code": "0016",
    "title": "Farm - Orchard & Drivers",
    "properties": {
      "ncci": "0016"
    },
    "states": [
      {
        "code": "AR",
        "name": "Arkansas",
        "products": [
          {
            "code": "wc"
          }
        ]
      },
      {
        "code": "CA",
        "name": "California",
        "products": [
          {
            "code": "wc"
          }
        ]
      }
    ]
  },
  {
    "code": "0019",
    "title": "Farm: Fish Hatchery Or Pond & Drivers",
    "properties": {
      "ncci": "0019"
    },
    "states": [
      {
        "code": "HI",
        "name": "Hawaii",
        "products": [
          {
            "code": "wc"
          }
        ]
      }
    ]
  },
  {
    "code": "0031",
    "title": "VEGETABLE, BERRY, OR GRAPE FARM & DRIVERS",
    "properties": {
      "ncci": "0031"
    },
    "states": [
      {
        "code": "NY",
        "name": "New York",
        "products": [
          {
            "code": "wc"
          }
        ]
      }
    ]
  }
]

Step 2: Initialize PayloadBuilder with OAS Schema

The PayloadBuilder is the core component of the SDK handling data point management, business rules, and payload generation:

import PayloadBuilder from '@briza/oas-sdk'

const oas = getOAS()

const quoteBuilder = new PayloadBuilder(oas)

Step 3: Collect Data Points and Build Your Form

After initializing your PayloadBuilder, you have multiple options for collecting data points and building your form.

[
  {
    "title": "EffectiveDt",
    "description": "Effective date (YYYY-MM-DD)",
    "type": "string",
    "format": "date",
    "required": true,
    "requiredForBind": true
  },
  {
    "title": "L1LocationState",
    "description": "The state of physical location of business",
    "type": "string",
    "enum": [
      "AK",
      "AL",
      //...
      "WV",
      "WY"
    ],
    "required": true,
    "requiredForBind": true
  },
  {
    "title": "L1Payroll1FullTimeEmployees",
    "description": "Number of full time employees",
    "type": "number",
    "required": true,
    "requiredForBind": true
  },
  {
    "title": "L1Payroll1Payroll",
    "description": "Payroll",
    "type": "integer",
    "format": "int32",
    "required": true,
    "requiredForBind": true
  },
  {
    "title": "Question29",
    "description": "Are you or the insured aware of any losses in the last four years?",
    "type": "string",
    "enum": ["Yes", "No"],
    "required": false,
    "requiredForBind": true
  },
  {
    "title": "Question313",
    "description": "Is gunite used in the installation of pools?",
    "type": "string",
    "enum": ["Yes", "No"],
    "required": false,
    "requiredForBind": true,
    "condition": [
      "AND",
      ["IN", "$L1LocationState", ["AK", "AL"]],
      ["IN", "$L1Payroll1ClassCode", ["5223"]]
    ]
  },
  {
    "title": "Question489",
    "description": "Do employees service or repair transmitters?",
    "type": "string",
    "enum": ["Yes", "No"],
    "required": false,
    "requiredForBind": true,
    "condition": [
      "AND",
      ["IN", "$L1LocationState", ["DE", "PA"]],
      ["IN", "$L1Payroll1ClassCode", ["0936"]]
    ]
  }
]

In this flow, you retrieve all data points defined in the schema and implement your own processing logic:

const allDataPoints = quoteBuilder.getAllDataPoints()

// Process data points using your own form / UI
const processDataPoints = (dataPoints, answers) => {
  // Your custom implementation:
  // 1. Determines which questions to show based on your own conditional logic
  // 2. Handles validation, dependencies, and UI rendering
  // 3. Manages the collection of answers until all required fields are complete
}

const initialAnswers = {
  State: 'CA',
  ClassCode: '12345'
}

const answerSet = await processDataPoints(allDataPoints, initialAnswers)

Use this approach when you:

• Want complete control over the form flow and UI
• Have specific UI/UX requirements that need custom implementation
• Prefer to handle all conditional logic in your own application code
• Want to pre-process or transform data points before showing them to users
• Want a holistic view of everything that is asked for an integration. For reporting, curation, or your own automation.

In this flow, in addition to having data about all data points you can get only the possible data points based on initial values:

const initialAnswers = {
  State: 'CA',
  ClassCode: '12345'
}

const possibleDataPoints =
  quoteBuilder.getPossibleDataPointsForValues(initialAnswers)

// Implement your own logic to process these possible data points
const processWithYourLogic = async (possibleDataPoints, currentAnswers) => {
  // Your implementation for:
  // 1. Deciding which questions to show and when
  // 2. Evaluating conditions as answers change
  // 3. Collecting all required answers

  // You can use the Illogical library directly for evaluating conditions
  // if you want to match the SDK's behavior

  let finalAnswers = { ...currentAnswers }

  // Your code to collect all answers
  return finalAnswers
}

const answerSet = await processWithYourLogic(possibleDataPoints, initialAnswers)

Use this approach when you:

• Want to know the full scope of potential questions upfront
• Prefer to implement your own condition evaluation logic
• Want to optimize form rendering by knowing all possible questions
• Need to support complex multi-step forms with your own navigation logic

In this flow, you leverage the SDK's conditional logic processing to show exactly what's needed at each step:

// Identify unanswered active data points
const getUnansweredActiveDataPoints = (answerSet) => {
  return quoteBuilder
    .getActiveDataPointsForValues(answerSet)
    .filter((dp) => answerSet[dp.title] === undefined)
}

let answerSet = {
  State: 'CA',
  ClassCode: '12345'
}
let unansweredActiveDataPoints = getUnansweredActiveDataPoints(answerSet)

// Collect answers until all active data points are answered
while (unansweredActiveDataPoints.length > 0) {
  // Collect answers for the active data points
  const collectedAnswers = await collectAnswersFromUser(
    unansweredActiveDataPoints
  )

  // Update answer set with collected answers
  Object.assign(answerSet, collectedAnswers)

  // Check if there are new active data points based on the new answers
  unansweredActiveDataPoints = getUnansweredActiveDataPoints(answerSet)
}

Use this approach when you:

• Want the simplest integration with minimal conditional logic implementation
• Prefer a progressive disclosure form where questions appear as needed
• Want to rely on the SDK to determine exactly which questions to show
• Need to minimize the number of questions shown to users at any time

Step 4: Build the Quote Request Payload

Build a payload for the quote request using the collected answers:

const answerSet = {
  // Answers collected from your workflow
  State: 'CA',
  ClassCode: '12345',
  EffectiveDt: '2026-01-01',
  BusinessPurposeTypeCd: 'NBQ',
  PolicyNumber: 'POLICY-12345',
  // ...
}

const indication = true
const payloadResult = quoteBuilder.buildPayload(answerSet, indication)

const result = payloadResult.result  // success or error

const payload = payloadResult.payload

Important: Ensure all active required data points have values before this step to avoid validation failures.

Step 5: Submit the Quote Request

Send the payload to the carrier API and process the response:

// Set authentication paramaters using your carrier API keys
const parameters = {
  headers: {
    Authorization: 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  }
}

// Send the quote request and receive the carrier's response
const response = await quoteBuilder.getQuoteForPayload(payload, parameters)

// Extract standardized quote properties from the response
const quoteProperties = quoteBuilder.getQuoteProperties(response)

console.log('Premium:', quoteProperties.premium)
console.log('Quote ID:', quoteProperties.quoteId)

The getQuoteProperties(response) method provides a normalized view of carrier-specific responses, making it easier to handle multiple integrations consistently.

Key SDK Methods Reference

| Method | Description | Used in Flow | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | | getAllDataPoints() | Returns the complete set of all data points defined in the OAS. | Flow 1 | | getPossibleDataPointsForValues(answerSet) | Returns all data points that might be needed based on provided answers (includes optional and conditionally required data points). | Flow 2 | | getActiveDataPointsForValues(answerSet) | Returns only the data points that are currently active based on conditional logic evaluation. | Flow 3 | | buildPayload(answerSet, indication) | Creates a structured API payload from the provided answers (returns success or error object). | All flows | | getQuoteForPayload(payload, parameters) | Sends the payload to the carrier API and returns the raw response. | All flows | | getQuoteProperties(response) | Extracts standardized properties from carrier-specific responses into a consistent format. | All flows |

References

• Illogical: Engine used to parse the raw logical and comparison expressions.

Patents

• U.S. Patent No.: 12,388,588
• Owner: Briza