Producer code access by resource
The table below provides a reference for how resources can be accessed by external users using the producer codes resource access strategy.
The table lists the resources, the endpoints, the type of access (view, edit, modify, delete), and whether the access is restricted to a limited set of fields. It also describes the business relationship the caller must have to the resource in order to access it. The table does not list resources which cannot be accessed.
The Entity relationship flow used to determine access column depicts how BillingCenter determines the business relationship between the provided producer codes and specific resources in the data model. The > symbol indicates that there is a reference between the data entities.
For example, to determine if a caller can access an invoice, BillingCenter first gets the invoice items on the invoice. BillingCenter checks if there are active item commissions for these invoice items. For each active item commission, BillingCenter gets the associated policy commission. For the policy commissions, BillingCenter checks if there is a producer code matching the caller's provided producer codes.
Therefore, this chain of entity relationships can be depicted as follows:
- ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Invoice
In some cases, the relationship of the producer code to the target resource is not relevant. This is noted in the table.
Billing API
| Resource and endpoints | How BillingCenter determines access | Entity relationship flow used to determine access |
|---|---|---|
| Account
|
Callers can access a restricted view of the account if one of
their producer codes has:
|
ProducerCode > PolicyCommission > PolicyPeriod > Account OR ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > Account |
| Account-level charge
|
Callers can access a restricted view of account-level charges if
one of their producer codes has:
|
Producer Code > Policy Commission > Policy Period > Account > Charge OR Producer Code > Policy Commission > Item Commission > InvoiceItem > Charge |
| Account contact
|
If one of the caller’s producer codes has access to the account, the caller can access a restricted view for all account contacts. | ProducerCode > PolicyCommission > PolicyPeriod > Account
> AccountContact OR ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > Account > AccountContact |
| Account delinquency process
|
If one of the caller’s producer codes has access to the account, the caller can access a restricted view for account delinquencies. | ProducerCode > PolicyCommission > PolicyPeriod > Account
> AccountContact > AccountDelinquencyProcess
OR ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > Account > AccountDelinquencyProcess |
| Account invoice
|
Callers can access account invoices with invoice items on which they earn commission. A restricted view of the invoices is provided. | ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Invoice |
| Agency bill payment/agency bill money received
|
Callers with at least one producer code on the producer can GET all that producer's agency bill payments. Callers with at least
one producer code but not all producer codes on the producer can
POST or modify agency bill payments only if the payments do not
have distributions. Callers with this level of access cannot
create, modify, or execute payments with distributions. (Note
that to specify a distribution when creating an agency bill
payment, you include the Callers with access to all producer codes on a producer have access to work with that producer's agency bill payments and their distributions. They can GET, POST, DELETE, execute, and modify agency bill payments with and without distributions. |
Producer Code > Producer > AgencyBillMoneyRcvd OR Producer Code > PolicyCommission > ItemCommission > InvoiceItem > AgencyPaymentItem > AgencyBillMoneyRcvd |
| Agency cycle payment/agency bill distribution
|
Callers with at least one producer code on the producer can view all of that producer's agency cycle payments (distributions). |
Producer Code > Producer > AgencyBillMoneyRcvd > AgencyCyclePayment |
| Agency payment item/distribution item
|
Callers with at least one producer code on the producer can view all of that producer's agency payment items. | Producer Code > PolicyCommission > ItemCommission > InvoiceItem >AgencyPaymentItem |
| Agency bill suspense items/agency suspense payment
items
|
Callers with at least one producer code on the producer can view all of that producer's agency bill suspense items. Callers that have all producer codes on a producer can release agency bill suspense items owned by that producer. If a caller is missing one or more producer codes, they cannot release agency bill suspense items. |
Producer Code > Producer > AgencyBillMoneyRcvd > AgencySuspPmntItem |
| Agency bill cycle
|
Callers can GET agency bill cycles if they earn commission in the primary role on at least one item on the cycle’s statement invoice. Restricted fields on the statement invoice are also restricted when GETing agency bill cycles. | ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > StatementInvoice > AgencyBillCycle |
| Agency bill payment exception
|
Callers can view agency bill payment exceptions associated with invoice items that the producer code earns commission on in the primary role. | ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > PaymentException |
| Charge commission
|
Callers can GET all charge commissions for policy commissions they have access to. | ProducerCode > PolicyCommission > ChargeCommission |
| Charge invoice item
|
Callers get unrestricted access if they have the producer code that is actively earning commission on the invoice item in the primary role. Callers get restricted access to the invoice item if they have a producer code with a non-primary status that is actively earning commission on the invoice item. | ProducerCode > PolicyCommission > ItemCommission > InvoiceItem |
| Claim charge
|
Charges on a claim billing instruction can have a producer or an account as a payer. If the charge has a producer as the
payer, a caller that has the charge’s payer producer code can
view the charge (specified in the
|
ProducerCode > BillingInstruction > Charge OR Producer Code > PolicyCommission > PolicyPeriod > Account > Charge OR ProducerCode > Policy Commission > ItemCommission > InvoiceItem > Charge |
| Disbursement
|
Callers with access to at least one producer code on the producer can access a restricted view of that producer’s disbursements. Only agency bill disbursements can be viewed. | ProducerCode > Producer > AgencyDisbursement |
| Invoice
GET
/billing/v1/accounts/{accountId}/invoice-streams/{invoiceStreamId}/invoices |
Callers can access a restricted view of invoices if there is an invoice item on the invoice for which one of their provided producer codes is earning commission. | ProducerCode > PolicyCommission > ItemCommission >InvoiceItem > Invoice |
| Invoice item
|
The caller gets unrestricted access if they have the producer code that is actively earning commission on the invoice item in the primary role. The caller gets restricted access to the invoice item if they have a producer code with a non-primary status that is actively earning commission on the invoice item. |
ProducerCode > PolicyCommission > ItemCommission > Invoice > InvoiceItem |
| Invoice stream
|
If the caller has access to at least one invoice on the invoice
stream, they can view the invoice stream. Callers with access to
view the invoice stream can also PATCH the invoice stream and
update the invoice days. The only PATCHable field is
|
ProducerCode > PolicyCommission > ItemCommission > Invoice > InvoiceStream |
| Item commission
|
Callers can access item commissions for charge commissions they have access to. | ProducerCode > PolicyCommission > ChargeCommission > ItemCommission |
| Policy
|
Callers can access a restricted view of policies for policy periods on which they earn commission. |
ProducerCode > PolicyCommission > PolicyPeriod > Account > PolicyPeriod > Policy OR ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > Account > PolicyPeriod > Policy |
| Policy commission
|
If the caller provides a producer code associated with a policy commission, they get access to the full policy commission. | ProducerCode > PolicyCommission |
| Policy period
|
Callers can access a restricted view of policy periods and change
the policy period payment plan if they provide producer codes with:
|
ProducerCode > PolicyCommission > PolicyPeriod OR ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > PolicyPeriod |
| Policy period-level charge
|
For commissionable policy period charges, callers must have active item commissions on the charge, or they must have inactive item commissions with a non-negative commissionAmount on the charge. For non-commissionable policy period charges, the caller must have one of the following:
|
ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge OR ProducerCode > PolicyCommission > PolicyPeriod > Policy > Account > Charge |
| Policy period contact
|
If the caller has access to the parent policy period, they get restricted access to all policy period contacts. | ProducerCode > PolicyCommission > PolicyPeriod > PolicyPeriodContact |
| Producer
|
If the caller provides all of the producer’s producer codes, they
get full access to the producer. They can also PATCH a subset of
producer fields: If the caller provides at least one of the producer’s producer codes, they get restricted access to the producer. |
ProducerCode > Producer |
| Producer code
|
Callers can view producer codes that are included in the JWT. | (Not relevant) |
| Producer contact
|
If callers provide all of a producer's producer codes in the JWT, they can access an unrestricted view of all contacts on the producer. If callers provide only some of a producer's producer codes in the JWT, they can access a restricted view of all contacts on the producer. There is no way to POST or DELETE the primary contact on a
producer when using the producer codes strategy. Callers with
all producer codes on a producer can PATCH only one field on
primary contacts: For secondary contacts on a producer, callers with all producer codes on the producer can POST and PATCH a subset of fields on the contact. |
ProducerCode > Producer > ProducerContact |
| Producer disbursement
|
Callers that provide any producer codes on the producer can access a restricted view of disbursements on that producer. | ProducerCode > Producer > Disbursement |
| Producer invoice
|
Callers can access a restricted view of producer invoices if they have an active item commission on the invoice. | ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Invoice |
| Producer payment instrument
|
If the caller has at least one producer code on the producer,
they get an unfiltered view of all producer payment
instruments. If the caller has all producer codes on the producer, they can PATCH and POST payment instruments owned by that producer. |
ProducerCode > Producer > PaymentInstrument |
| Universal payment instrument
|
If the caller provides a valid producer code, they get unrestricted access to view all universal payment instruments. | (Not relevant, as there is no defined universal payment instrument entity, and there is no need to determine a relationship between the producer code and the universal payment instruments.) |
Admin API
| Resource and endpoints | How BillingCenter determines access | Entity relationship flow used to determine access |
|---|---|---|
| Agency bill plan
|
The caller has view access to the agency bill plans for all producers they have access to. | ProducerCode > Producer > AgencyBillPlan |
| Billing plan
|
If the caller provides a valid producer code, they get access to all billing plans. | (Not relevant, as there is no need to determine a relationship between the producer code and specific billing plans.) |
| Charge pattern rate
|
The caller has access to the charge pattern rates for the commission subplans they can access. | ProducerCode > CommissionPlan > CommissionSubPlan > CommissionSubPlanChargePatternRate |
| Commission plan
|
The caller has access to the commission plans associated with the producer codes provided in the JWT. | ProducerCode > CommissionPlan |
| Commission subplan
|
The caller has access to commission subplans for the commission plans they can access. | ProducerCode > CommissionPlan > CommissionSubPlan |
| Commissionable charge item
|
The caller has access to the commissionable charge items for the commission subplans they can access. | ProducerCode > CommissionPlan > CommissionSubPlan > CommissionSubPlanChargePatternRate |
| Delinquency event
|
The caller can view delinquency plan events for all the delinquency reasons it can access. |
ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > PolicyPeriod > DelinquencyPlan > DelinquencyPlanReason > DelinquencyPlanEvent OR ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > PolicyPeriod > Account >DelinquencyPlan > DelinquencyPlanReason > DelinquencyPlanEvent |
| Delinquency plan
|
The caller has access to delinquency plans associated with the policies and accounts accessible to the provided producer codes. |
ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > PolicyPeriod > DelinquencyPlan OR ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > PolicyPeriod > Account > DelinquencyPlan |
| Delinquency reason
|
The caller can view delinquency reasons for all the delinquency plans it can access. |
ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > PolicyPeriod > DelinquencyPlan > DelinquencyPlanReason OR ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > PolicyPeriod > Account > DelinquencyPlan > DelinquencyPlanReason |
| Incentive
|
The caller has access to the incentives for the commission subplans they can access. | ProducerCode > CommissionPlan > CommissionSubPlan > Incentive |
| Payment Plan
|
If the caller provides a valid producer code, they get unrestricted access to all payment plans. | (Not relevant, as BillingCenter does not determine a relationship between the producer code and payment plans.) |
| Payment plan override
|
If the caller provides a valid producer code, they get unrestricted access to all payment plans overrides. | (Not relevant, as BillingCenter does not determine a relationship between the producer code and payment plan overrides.) |
| Section rate
|
The caller has access to the section rates for the commission subplans they can access. | ProducerCode > CommissionPlan > CommissionSubPlan > CommissionSubPlanSectionRate |
| Subplan rate
|
The caller has access to the subplan rates for the commission subplans they can access. | ProducerCode > CommissionPlan > CommissionSubPlan > CommissionSubPlanRate |
Charge access in the case of producer transfer
Occasionally, it may be necessary for an insurer to transfer one or more policy periods from one producer to another. When a producer transfer occurs, the producer code for a given role on a policy period is switched to a new producer code. Following the transfer, the initial producer code’s policy commissions, charge commissions, and item commissions are no longer active.
- Point-in-time: Unearned commission and future commission is assigned to the new producer. However, the original producer retains any commission already earned.
- Retroactive: All commission is reassigned to the new producer.
-
Future: Only the commission for future charges is transferred to the new producer. This includes commission on new charges added to the existing policy period and charges for renewals of the policy period. The original producer retains all existing commission for the current policy period, whether it is in reserve or earned.
For more information about these producer transfers, see the BillingCenter Application Guide.
BillingCenter has logic to determine whether the old producer and the new producer code can access charges based on the type of producer transfer. This logic ensures that callers are not able to access charge information about charges they do not have an appropriate business relationship with.
For example, following a retroactive transfer, the old producer code cannot access any charges. However, following a point-in-time transfer, the old producer code can access charges created before the transfer.
- The old producer code is the producer code associated with the charge before the transfer
- The new producer code is the producer code associated with the charge after the transfer
| Transfer type | Type of charge | Can the old producer code access the charge? | Can the new producer code access the charge? |
|---|---|---|---|
| Point-in-time | Commissionable charge created before transfer | Yes | Yes |
| Account-level charge created before transfer | Yes | Yes | |
| Non-commissionable policy period charge created before transfer | Yes | Yes | |
| Claim charge created before transfer, with account as the payer | Yes | Yes | |
| Account-level charge created after transfer | No | Yes | |
| Non-commissionable policy period charge created after transfer | No | Yes | |
| Claim charge created after transfer, with account as the payer | No | Yes | |
| Retroactive | Commissionable charge created before transfer | No | Yes |
| Account-level charge created before transfer | No | Yes | |
| Non-commissionable policy period charge created before transfer | No | Yes | |
| Claim charge created before transfer, with account as the payer | No | Yes | |
| Future | Commissionable charge created before transfer | Yes | No |
| Account-level charge created before transfer | Yes | Yes | |
| Non-commissionable policy period charge created before transfer | Yes | Yes | |
| Claim charge created before transfer, with account as the payer | Yes | Yes | |
| Account-level charge created after transfer | No | Yes | |
| Non-commissionable policy period charge created after transfer | No | Yes | |
| Claim charge created after transfer, with account as the payer | No | Yes |