Producers

A producer is typically an agent or broker authorized to distribute an insurance product on behalf of one or more insurance carriers (also known as institutions). Each licensed agent on your platform is a producer, who can be given access to individual insurance products.

‍

Producers at Herald

Each producer is given a unique [.h-code]producer_id[.h-code] which is used to manage their access to insurance producers, and attribute quotes and sales to the correct producer. A [.h-code]producer_id[.h-code] is required when submitting an application in order for us to identify the producer and confirm that they are appointed to sell the intended product.

In Herald’s ecosystem, producers are a part of a larger hierarchy that represents the real world. In the real-world, a producer belongs to a distributor (such as a retail or wholesale brokerage) and may be grouped with other producers based on attributes such as their office or the division they are a part of. These real-world relationships are reflected in our API, where each producer is required to belong to a distributor and can be associated with multiple groups.

When submitting an application we use [.h-code]producer_id[.h-code] to communicate these relationships with the carrier, so they identify who is requesting insurance.

In order to make submissions and get quotes with Heralds API, you must first create producers with the relationships listed above, and then connect those producers to products.

‍

‍

Producer Relationships

Creating a producer with Herald's API requires some of these real-world relationships. Every producer must belong to an individual distributor, and can belong a number of different groups such as an office or division. We’ve set up this hierarchy for 2 primary reasons:

1. Managing Product Access: Product availability can range drastically depending on an individual producer, their division or office, and the distributor they belong to. Managing product access based on different levels of your users is very important. Here are some examples where you would want to restrict product access to certain distributors, groups, and producers:

• You could have multiple distributors: Agency A offers a range of Business Insurance products, and Agency B specialize in Cyber Insurance. Producers that belong to Agency A could be given access to your full suite of products, and producers that belong to Agency B only have access to Cyber Insurance products.
• Agency C also specializes in Cyber Insurance, but they only have an appointment with a single carrier (institution). Producers that belong to Agency C only have access to a subset of the Cyber Insurance products that Agency B has.
• Agency A, who offers a range of Business Insurance products, splits their producers into 2 divisions (Groups). One division specializes in surplus products, and the other specializes in admitted products. This distributor may want to restrict product access so that no individual producer has the ability to sell both admitted and surplus products.
• At the bottom of the funnel, there may be an individual producer that is not appointed to sell a certain product that the rest of the producers have access to.

2. Communicating with Carriers: When submitting an application for a quote, the carrier wants to know who is requesting the quote. “Who” typically encompasses the full hierarchy above. Carriers want to know details like which individual producer is requesting the quote, which office they work at, and which distributor they belong to. A carrier may use this information for multiple purposes, such as:

• Confirming that the distributor, office, or producer is in fact appointed and allowed to sell their products.
• Reporting on quotes and bound policies for an individual distributor, office, division, or producer.

You can create and manage distributors, groups, and producers using the API. Read more about each level of the hierarchy below.

‍

Distributors

A distributor is any organization that distributes Commercial Insurance, acting as an intermediary between an insurance carrier and producers (insurance agents and brokers). Creating a distributor is required before you can create a producer.

• If your platform only serves an internal distribution team, you only need to create 1 distributor that houses all of your producers.
• If your platform serves multiple distributors, you can continually create multiple distributors and their respective producers.

You can create and manage distributors using [.h-endpoint-link]/distributors[.h-endpoint-link].

Here are some important details about distributors:

• You can create multiple distributors.
• You must create a distributor before you create a producer.
• Each distributor can have multiple producers.
• Each distributor can have multiple groups.
• Heralds internal team manages a distributors access to insurance products.
• A distributors access to insurance products is managed internally by Herald. To give a distributor access to a new insurance product, contact Heralds support team.

‍

Groups

Groups allow you to group a cohort of producers together based on common attributes, which can be used to manage product access and represent these cohorts to carriers. There are 3 group types: [.h-code]office[.h-code], [.h-code]region[.h-code], and [.h-code]division[.h-code].

[.icon-circle-blue][.icon-circle-blue] It’s important to note, groups are not required to create a producer. However, groups of a certain type can become required when trying to connect to a certain product. For example, 1 carrier may not require you to tell them which office a producer belongs to, but another carrier may require this information.

You can create and manage groups using [.h-endpoint-link]/groups[.h-endpoint-link]. You can create a groups at any point in time to group producers together, with every group belonging to a single distributor. You can add and remove producers from groups using [.h-endpoint-link]/producers[.h-endpoint-link].

Here are some important details about Groups:

• You can create multiple groups on each distributor.
• You must create a distributor before you create a group.
• Each group can have multiple producers.
• Each group can only belong to a single distributor.
• A groups access to insurance products is managed internally by Herald. To give a group access to a new insurance product, contact Heralds support team.

‍

Producers

Each licensed agent on your platform is a producer, with the ability to submit applications for quotes for the products they have access to. A producer, also known as a retail broker or agent, has to be appointed and authorized to sell a product from a carrier.

You can create and manage producers using [.h-endpoint-link]/producers[.h-endpoint-link]. Once you’ve created a producer, you can give them access to products by making connections. Each producer is given a [.h-code]producer_id[.h-code], which is required when submitting an application in order for us to confirm that the producer has access to the requested product, and to communicate with carriers who is requesting the quote. We use [.h-code]producer_id[.h-code] in order to tell a carrier who the producer is, which distributor they belong to, and any relevant groups they are a part of.

Here are some important details about Producers:

• You can create multiple producers.
• You must create a distributor before you create a producer.
• Each producer can only belong to a single distributor.
• Each producer can belong to multiple groups.
• You can give a producer access to products using [.h-endpoint-link]/connections[.h-endpoint-link] as long as the distributor the producer belongs to has access to the product.

‍

Connect Producers to Products

You can give producers access to individual products by making connections. A Connection is the relationship between an individual producer, via [.h-code]producer_id[.h-code], and an individual product, via [.h-code]product_id[.h-code]. Making a connection may require authentication values, which serve as a way for carriers to verify who the producer is and that they are authorized to sell the requested product.

An authentication value can be something as simple as a producers’ username and password to log in to the carriers portal, validating that the producer is who they say they are. Authentication values are unique for each product. You can locate all authentication parameters in the Producer Connection Appendix, or by making a connection intent to receive the correct parameters for an individual product.

Learn more about connections.

‍

Using Producers

When submitting an application, a producer_id is required. If the producer doesn’t have access to one or more of the products, you’ll receive a 400 error like the example below.

Copied

"errors": [
   {
     "code": "invalid_format",
     "message": "The following Product IDs are not available for the given Producer ID: [prd_m3qr_herald_general_liability]"
   }
]