Connections

Give producers access to insurance products by making connections.

In order to sell a carrier's insurance products, a producer has to have an appointment with the insurance carrier. An appointment from a carrier means the producer is authorized to sell some or all of the carriers insurance products. You can give a producer access to insurance products by making connections, which requires that the producer is appointed and authorized to sell the product.

[.icon-circle-blue][.icon-circle-blue] We do not directly offer or facilitate carrier appointments for individual producers, but we are always more than happy to make organization-level introductions for your brokerage or platform if you are interested in working with a new carrier partner in our network.

Connections at Herald

A connection is the relationship between an individual producer and an individual product. Making a connection gives the producer access to quote the connected product via API. Quoting with Herald operates with the same restrictions as quoting anywhere else- the producer has to be appointed and authorized by the insurance carrier to sell the product. When making a connection, we confirm this appointment through authentication values.

Authentication Values

Authentication values are the values that represent a producer at the API level. When creating a producer, you submit real-world representations of a producer such as their name, email, the distributor they work for, and attributes such as their office address or division (groups). At the API level, carriers tend to abstract those real-world representations into their own forms of authentication.

What do we mean by that? Let’s say you create a producer with the following information:

  • Name: Steve Smith
  • Email: steve@logan-ins.com
  • Distributor: Logan Insurance Group
  • Office: 136 S. Broadway, STE 204, New York, NY 10024

These are the real-world representations of the producer. Now let’s say you want to connect Steve to a Cyber Insurance product for Carrier A. In order for Carrier A to verify the identity and appointment of Steve Smith, they may require API level representations. Carrier A’s API may represent Steve Smith by his [.h-code]agent_id[.h-code]- their own internal UUID to represent Steve Smith.

When making a connection, these API level representations are submitted as [.h-code-link]auth_values[.h-code-link], with each value corresponding to an [.h-code]auth_parameter_id[.h-code]. The required set of authentication values is unique to each product, and not all products require authentication values. In fact, some carrier APIs ingest these real-world representations directly. The most common example is a producers email, which may be the only unique identifier for a producer in a carriers system.

Authentication values are a similar concept to risk, coverage, and admin values, which is how information about an applicant is submitted on an application. Here are some examples of auth_values.

[.h-small-text](The auth parameter ids below are using a fake carrier name “Pigeon” in place of the actual carriers name)[.h-small-text]

auth_parameter_id Description
ath_sn37_pigeon_username A producers username to log into the Pigeon Carrier Portal
ath_nid9_pigeon_password A producers password to log into the Pigeon Carrier Portal
ath_byw7_pigeon_agent_id A producers UUID assigned by Pigeon

Create Connections

You can create a connection for any producer using [.h-endpoint-link]/connections[.h-endpoint-link], as long as the producer's distributor has access to the product. You can find the set of required authentication values by product in our Producers Connection Appendix. You can also get the required [.h-code]auth_values[.h-code] for a specific product dynamically by creating a Connections Intent.

Each connection you create is given an [.h-code]id[.h-code] and a [.h-code]status[.h-code]. The connections status communicates if the producer can successfully make a submission to get a quote for the product. For most products, creating a connection should result in an [.h-code]active[.h-code] status immediately. However, some carriers have more robust forms of authentication, and confirming that a producer is authorized so sell a product may not be instant. In these cases, the connection will have a [.h-code]referred[.h-code] status, meaning that more action is required from either the carrier or Herald's team. A referred status does not mean more information is needed from you, and should typically be resolved in 24 hours.