Search for producers

You might need to access a specific producer, but you do not know the producer's ID. You can use the following endpoint to search for the producer:
  • POST /billing/v1/search/producers

In the request body, you can specify search parameters. The response contains an array of producers that match all the search parameters.

String and typekey search parameters

You can search for producers using fields on the producer and on the producer's contacts.

For all string search parameter fields, BillingCenter supports partial string matching. The search value must match the beginning of the string.

For example, the following matches a producer that has a contact with the last name "Newton":

{
  "data": {
    "attributes": {
      "contactLastName": "newto"
    }
  }
}

The following does not match, because the beginning of the string is not included:

{
  "data": {
    "attributes": {
      "contactLastName": "ewton"
    }
  }
}
Note: You can search for producers based on both primary and non-primary contacts.

You can also search using typekey references, such as country, state, or currency. Typekey references do not match on partial strings, but they are case-insensitive.

For example, you can search for producers with a contact in California:

{
  "data": {
    "attributes": {
      "contactState": {
        "code": "ca"
      }
    }
  }
}

The hasAgencyBillPlan field

The Boolean field hasAgencyBillPlan filters producers based on whether or not they have an agency bill plan.

{
  "data": {
    "attributes": {
      "hasAgencyBillPlan": true
    }
  }
}

In the BillingCenter user interface, this value appears on the producer search page as a check box with the label Has Agency Bill Plan. The check box is always either checked or unchecked, so by default, the user interface search uses this field as a search parameter.

In Cloud API, hasAgencyBillPlan is not used as a search parameter by default. If this field is not set in the request, producers both with and without agency bill plans are returned. Therefore, you have the following options for this field:

  • Not set (null): Producers with agency bill plans and without agency bill plans are returned
  • false: Only producers without agency bill plans are returned
  • true: Only producers with agency bill plans are returned

Searching with no search parameters

You can search without including search parameters by sending an empty data wrapper.

{
  "data": {
    "attributes": {
    }
  }
}

If there are more than 300 producers to be returned, BillingCenter returns an error.

Response details

BillingCenter returns a list of producers. The fields for each producer only detail the producer itself, not any related entities such as contacts.

The following is an example of a request that returned one producer:

Command 
POST /billing/v1/search/producers

Request body

{
  "data": {
    "attributes": {
      "producerName": "producer alpha"
    }
  }
}

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "advanceBalance": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "commissionPaidYearToDateForAllCurrencies": {
                    "amount": "0",
                    "currency": "usd"
                },
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "defaultPaymentInstrument": {
                    "displayName": "Responsive",
                    "id": "bc:S-eni4CeguGPoOI0q6DJd",
                    "type": "UniversalPaymentInstrument",
                    "uri": "/billing/v1/universal-payment-instruments/bc:S-eni4CeguGPoOI0q6DJd"
                },
                "holdStatement": false,
                "id": "bc:SLZEvBWJZiE3NAx2-Rb0_",
                "name": "Producer Alpha",
                "recurDayOfMonth": 30,
                "recurPeriodicity": {
                    "code": "monthly",
                    "name": "Monthly"
                },
                "statementHoldNegativeLimit": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "statementHoldPositiveLimit": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "suspenseAmount": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "tier": {
                    "code": "gold",
                    "name": "Gold"
                },
                "totalCommissionExpense": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "totalCommissionPayable": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "totalCommissionReserve": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "unappliedAmount": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "writeoffExpense": {
                    "amount": "0",
                    "currency": "usd"
                }
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/billing/v1/producers/bc:SLZEvBWJZiE3NAx2-Rb0_",
                    "methods": [
                        "get",
                        "patch"
                    ]
                }
            }
        }
    ],
    "links": {
        "first": {
            "href": "/billing/v1/search/producers",
            "methods": [
                "post"
            ]
        },
        "self": {
            "href": "/billing/v1/search/producers",
            "methods": [
                "post"
            ]
        }
    }
}