Create and Manage Distributors

A distributor is any organization that distributes Commercial Insurance, acting as an intermediary between an insurance carrier and producers (insurance agents and brokers). When creating producers with Heralds API, distributors serve as a layer between your platform and producers.

You must create a distributor before you can create a producer.

Create a Distributor

You can create a distributor using [.h-code]POST[.h-code] [.h-endpoint-link]/distributors[.h-endpoint-link] which only requires the distributors [.h-code]name[.h-code] and [.h-code]domains[.h-code]. Creating a distributor should look the example below.

POST /distributors

Copied

{
  "name": "Logan Insurance Group",
  "domains": [
    "logan-ins.com"
  ]
}
 

Response

Copied

{
  "distributor": {
    "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
    "name": "Logan Insurance Group",
    "domains": [ "logan-ins.com" ],
    "groups": null,
    "producers": null,
    "products": null
  }
}
 

As shown above, the response includes the information above as well as:

• The [.h-code]id[.h-code] for the distributor.
• An array of [.h-code]groups[.h-code] that belong to the distributor
• An array of [.h-code]producers[.h-code] that belong to the distributor
• An array of [.h-code]products[.h-code] the distributor has access to.

Note that when creating a new distributor, groups, producers, and products will all be [.h-code]null[.h-code]. As you create new groups and producers below this distributor, and give this distributor access to products, those relationships will be present in the response. You can get this information using [.h-code]GET[.h-code] [.h-endpoint-link]/distributors/{distributor_id}[.h-endpoint-link].

[.icon-circle-blue][.icon-circle-blue] Producers, groups, and products are read only in the distributors object. To add a producer or group to a distributor, you simply create a new producer or group which requires a [.h-code]distributor_id[.h-code]. A distributor's products are managed by Herald's team.

‍

Get all Distributors

You can get a list of all your distributors using [.h-code]GET[.h-code] [.h-endpoint-link]/distributors[.h-endpoint-link]. The response will include an array of all distributors you have created. In the example above, we created a new distributor. Let’s look at an example response assuming that you have already created a distributor with groups, producers, and products in the past.

GET /distributors

Copied

{
  "distributors": [
    {
      "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
      "name": "Logan Insurance Group",
      "domains": [
        "logan-ins.com"
      ],
      "groups": null,
      "producers": null,
      "products": null
    },
    {
      "id": "7901a35e-a6ca-40bf-b370-68d888a28c1c",
      "name": "Regional Wholesale",
      "domains": [
        "regionalwholesale.com"
      ],
      "groups": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "type": "office",
          "value": {
            "line1": "1640 Riverside Drive",
            "line2": "Floor 3",
            "line3": "Suite 5",
            "organization": "ACME Corporation",
            "city": "Hill Valley",
            "state": "CA",
            "postal_code": "95420",
            "country_code": "USA"
          }
        }
      ],
      "producers": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "Harold Whetstone",
          "email": "harold@regionalwholesale.com",
          "external_id": "100234"
        },
        {
          "id": "ea631eca-07d1-44d4-ad2a-27358b0255d0",
          "name": "Sally Matthews",
          "email": "sally@regionalwholesale.com",
          "external_id": null
        }
      ],
      "products": [
        {
          "id": "prd_0050_herald_cyber",
          "name": "Herald Cyber",
          "institution_id": "ins_vbh3_herald",
          "product_line": "cyber"
        }
      ]
    }
  ]
}
 

As you can see in the response above, the distributor that already has producers, groups, and products includes an array of objects for each concept.

• Each Group in the array contains the groups [.h-code]id[.h-code], [.h-code]typ[.h-code]e, and [.h-code]value[.h-code].
• Each Producer in the array contains the producers [.h-code]id[.h-code], [.h-code]name[.h-code], [.h-code]email[.h-code], and [.h-code]external_id[.h-code] (if you’ve provided one).
• Each Product in the array contains the products [.h-code]id[.h-code], [.h-code]name[.h-code], [.h-code]institution_id[.h-code], and [.h-code]product_line[.h-code].

‍

Update a Distributor

You can update a distributor using [.h-code]PUT[.h-code] [.h-endpoint-link]/distributors/{distributor_id}[.h-endpoint-link] which allows you to update the distributors [.h-code]name[.h-code] and [.h-code]domains[.h-code]. The body to update a distributor should look identical to the body for creating a distributor. Let’s say we want to change the name of the distributor we created earlier, the request would look like this:

PUT /distributors/{distributor_id}

Copied

{
  "name": "Logan and Sons Insurance Group, LLC",
  "domains": [
    "logan-ins.com"
  ]
}
 

Response

Copied

{
  "distributor": {
    "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
    "name": "Logan and Sons Insurance Group, LLC",
    "domains": [ "logan-ins.com" ],
    "groups": null,
    "producers": null,
    "products": null
  }
}
 

‍

Get a Distributor

Similar to getting all distributors, you can get the details of an individual distributor using [.h-code]GET[.h-code] [.h-endpoint-link]/distributors/{distributor_id}[.h-endpoint-link]  which will provide the details for that distributor. See an example below.

GET /distributors/{distributor_id}

Copied

{
  "distributor": {
    "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
    "name": "Logan and Sons Insurance Group, LLC",
    "domains": [ "logan-ins.com" ],
    "groups": null,
    "producers": null,
    "products": null
  }
}
 

‍

Adding Producers and Groups

Once you’ve created a distributor, you can create producers and create groups below that distributor. Creating a producer or group requires a [.h-code]distributor_id[.h-code].