Create and Manage 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 [.h-code]types[.h-code]: office, region, and division.

Every group belongs to a specific distributor. For example, you could create a group for each office that a distributor has. When creating producers for that distributor, you can assign each producer to their respective office.

You must create groups for a distributor at any point in time, and continually add and remove producers from groups.

‍

Create a Group

You can create a group using [.h-code]POST[.h-code] [.h-endpoint-link]/groups[.h-endpoint-link] which requires a [.h-code]type[.h-code], [.h-code]value[.h-code], and a distributor via [.h-code]distributor_id[.h-code]. Creating a group should look the example below.

POST /groups

Copied

{
  "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"
  },
  "distributor_id": "dab8023b-7f9e-4146-9614-a3d922d359b0"
}
 

Response

Copied

{
  "group": {
    "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"
    },
    "distributor_id": "aab8023b-7f9e-4146-9614-a3d922d359b0",
    "producers": null,
    "products": null
  }
}
 

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

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

Note that when creating a new group, producers and products will all be [.h-code]null[.h-code]. You can assign producers to individual groups as you create and manage producers, and Herald can give your groups access to products. As those things happen, those relationships will be present in the response. You can get this information using [.h-code]GET[.h-code] [.h-endpoint-link]/groups/{group_id}[.h-endpoint-link].

[.icon-circle-blue][.icon-circle-blue] Producers and products are read only in the groups object. To add a producer to a group, use [.h-endpoint-link]/producers[.h-endpoint-link]. A groups products are managed by Heralds team.

‍

Get all Groups

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

GET /groups

Copied

{
  "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"
      },
         "distributor_id": "aab8023b-7f9e-4146-9614-a3d922d359b0",
         "producers": null,
         "products": null
    },
    {
      "id": "8daac0af-2ad6-4676-bfaa-f23e974d7d79",
      "type": "division",
      "value": "Surplus Lines",
      "distributor_id": "aab8023b-7f9e-4146-9614-a3d922d359b0",
      "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 group that already has producers and products includes an array of objects for each concept.

• 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 Group

You can update a group using [.h-code]PUT[.h-code] [.h-endpoint-link]/groups/{group_id}[.h-endpoint-link] which allows you to update the groups [.h-code]value[.h-code] and [.h-code]type[.h-code]. The body to update a group should look identical to the body for creating a group. Let’s say we want to change the address of the office we created earlier, the request would look like this:

[.icon-circle-blue][.icon-circle-blue] Changing a groups’ [.h-code]type[.h-code] could affect the status of a connection for a producer. We recommend creating new groups instead of changing a groups [.h-code]type[.h-code].

PUT /groups/{group_id}

Copied

{
  "type": "office",
  "value": {
    "line1": "476 Rodeo Drive",
    "line2": "Suite 23",
    "line3": null,
    "organization": "ACME Corporation",
    "city": "Hill Valley",
    "state": "CA",
    "postal_code": "95425",
    "country_code": "USA"
  },
  "distributor_id": "dab8023b-7f9e-4146-9614-a3d922d359b0"
}
 

Response

Copied

{
  "group": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "type": "office",
    "value": {
       "line1": "476 Rodeo Drive",
       "line2": "Suite 23",
       "line3": null,
       "organization": "ACME Corporation",
       "city": "Hill Valley",
       "state": "CA",
       "postal_code": "95425",
       "country_code": "USA"
    },
    "distributor_id": "aab8023b-7f9e-4146-9614-a3d922d359b0",
    "producers": null,
    "products": null
  }
}
 

‍

Get a Group

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

GET /groups/{group_id}

Copied

{
  "group": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "type": "office",
    "value": {
       "line1": "476 Rodeo Drive",
       "line2": "Suite 23",
       "line3": null,
       "organization": "ACME Corporation",
       "city": "Hill Valley",
       "state": "CA",
       "postal_code": "95425",
       "country_code": "USA"
    },
    "distributor_id": "aab8023b-7f9e-4146-9614-a3d922d359b0",
    "producers": null,
    "products": null
  }
}
 

‍

Adding Producers

Once you’ve created a group, you can create producers and assign them to that group. Assigning a producer to a group requires the groups’ [.h-code]group_id[.h-code].