Create and Manage 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. Each producer belongs to a single distributor, and can belong to multiple groups.

You can create and manage a producer using the steps below, and then give them access to products by making connections.

‍

Create a Producer

You can create a producer using [.h-code]POST[.h-code] [.h-endpoint-link]/producers[.h-endpoint-link] which requires a [.h-code]name[.h-code], [.h-code]email[.h-code], and a distributor via [.h-code]distributor_id[.h-code]. You can also include the following optional information when creating or updating a producer:

• [.h-code]enabled[.h-code]: A flag to communicate if the producer is enabled or disabled. When not provided, it is set to [.h-code]true[.h-code]. When [.h-code]enabled: false[.h-code] the producer’s connections will remain active, however the producer will not have access to the Herald API.

• [.h-code]external_id[.h-code]: An external value you can set to associate the producer with your internal id for tracking. When not provided, it is set to [.h-code]null[.h-code].

• [.h-code]groups[.h-code]: An array of [.h-code]group_ids[.h-code] to associate a producer with a group. When not provided, it is set to an empty array [.h-code][][.h-code].

Creating a producer should look like the example below.

POST /producers

Copied

{
  "name": "Steven Smith",
  "email": "steven@logan-ins.com",
  "distributor_id": "dab8023b-7f9e-4146-9614-a3d922d359b0"
}
 

Response

Copied

{
  "producer": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Steven Smith",
    "email": "steven@logan-ins.com",
    "enabled": true,
    "distributor": {
       "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
       "name": "Logan Insurance Group",
       "domains": [
          "logan-ins.com"
       ],
    },
    "external_id": null,
    "groups": [],
    "connections": []
  }
}
 

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

• The [.h-code]id[.h-code] for the producer.
• An array of [.h-code]connections[.h-code]. Connections are the relationship between a producer and a product.

Note that when creating a new producer, connections will be an empty array [.h-code][][.h-code]. As you make connections for a producer, they will appear in the response.

Connect Producers to Products

Once you’ve created a producer, you can connect them to products. You can give a producer access to products by making a connection to any product the producer's distributor has access to.

Get all Producers

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

GET /producers

Copied

{
  "producers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "Steven Smith",
      "email": "steven@logan-ins.com",
      "enabled": true,
      "distributor": {
        "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
        "name": "Logan Insurance Group",
        "domains": [
          "logan-ins.com"
        ],
      },
      "external_id": null,
      "groups": [],
      "connections": []
    },
    {
      "id": "c0caf150-7730-11ed-a1eb-0242ac120002",
      "name": "Megan Stevens",
      "email": "megan@logan-ins.com",
      "enabled": true,
      "distributor": {
        "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
        "name": "Logan Insurance Group",
        "domains": [
          "logan-ins.com"
        ],
      },
      "external_id": null,
      "groups": [
         {
            "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"
            }
         }
      ],
      "connections": [
         {
            "id": "cd6aaf68-7730-11ed-a1eb-0242ac120002",
            "product_id": "prd_0050_herald_cyber",
            "status": "active"
         }
      ]
    }
  ]
}
 

As you can see in the response above, the producer that has a connection and belongs to a group includes an array of objects for each concept.

• Each Group in the array contains the groups [.h-code]id[.h-code], [.h-code]type[.h-code], and [.h-code]value[.h-code]
• Each Connection in the array contains the [.h-code]id[.h-code] and [.h-code]status[.h-code] for the connection, and the [.h-code]product_id[.h-code] that the producer is connected to.

‍

Get and Update a Producer

Before updating a producer, you can get the details of an individual producer using [.h-code]GET[.h-code] [.h-endpoint-link]/producers/{producer_id}[.h-endpoint-link] which will provide the details for that producer.

If you need to update information for a producer, there are two methods to make the update using PATCH and PUT

[.icon-circle-blue][.icon-circle-blue] Changing the distributor or group a producer belongs to could affect the [.h-code]status[.h-code] of a producers connection. If you are updating one of these for a producer, make sure the new distributor or group has access to the same products.

PATCH to update

You can update a producer using [.h-code]PATCH[.h-code] [.h-endpoint-link]/producers/{producer_id}[.h-endpoint-link] which will update information in the request. That can include [.h-code]name[.h-code], [.h-code]email[.h-code], [.h-code]enabled[.h-code], [.h-code]distributor[.h-code], [.h-code]external_id[.h-code] and/or [.h-code]groups[.h-code]. Let’s say you want to add the producer to a group and add an [.h-code]external_id[.h-code], the request would look like this:

PATCH /producers/{producer_id}

Copied

{
  "external_id": "PRD-77156",
  "groups": [
		"497f6eca-6276-4993-bfeb-53cbbbba6f08"
	]
}
 

Response

Copied

{
	"producer": {
		"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
		"name": "Steven Smith",
	  "email": "steven@logan-ins.com",
	  "enabled": true,
	  "distributor": {
			"id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
	    "name": "Logan Insurance Group",
	    "domains": [
	      "logan-ins.com"
	    ],
		},
	  "external_id": "PRD-77156",
	  "groups": [
			{
				"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"
			  }
			}
		],
	  "connections": []
	}
}
 

PUT to update

You can also update a producer using [.h-code]PUT[.h-code] [.h-endpoint-link]/producers/{producer_id}[.h-endpoint-link] which updates all information in the request. The request should include information that you want to update and that you want to stay the same. If excluded, optional fields will be set to the defaults mentioned above. Let’s say you want to add an say you want to add an [.h-code]external_id[.h-code].

First, check the details for the producer you want to update:

GET /producers/{producer_id}

Copied

{
	"name": "Steven Smith",
  "email": "steven@logan-ins.com",
  "enabled": true,
  "distributor": {
       "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
       "name": "Logan Insurance Group",
       "domains": [
          "logan-ins.com"
       ],
    },
  "external_id": null,
  "groups": []
}
 

Then send the following request to add an [.h-code]external_id[.h-code]:

PUT /producers/{producer_id}

Copied

{
  "name": "Steven Smith",
  "email": "steven@logan-ins.com",
  "enabled": true,
  "distributor_id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
  "external_id": "PRD-77156",
  "groups": []
}
 

Response

Copied

{
  "producer": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Steven Smith",
    "email": "steven@logan-ins.com",
    "enabled": true,
    "distributor": {
       "id": "dab8023b-7f9e-4146-9614-a3d922d359b0",
       "name": "Logan Insurance Group",
       "domains": [
          "logan-ins.com"
       ],
    },
    "external_id": "PRD-77156",
    "groups": [],
    "connections": null
  }
}