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

GET /billing/v1/accounts/{accountId}

Callers can access a restricted view of the account if one of their producer codes has:
  • An active policy commission on at least one policy period on the account
  • An active item commission on any charge on a policy period on the account
  • An inactive item commission with a commission amount greater than zero on any charge on a policy period for the account

ProducerCode > PolicyCommission > PolicyPeriod > Account

OR

ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > Account

Account-level charge

GET /billing/v1/accounts/{accountId}/charges

GET /billing/v1/charges/{chargeId}

Callers can access a restricted view of account-level charges if one of their producer codes has:
  • An active policy commission on at least one policy period on the account
  • An active item commission on the charge
  • An inactive item commission with a commission amount greater than 0 on the charge. Additionally, in this case, the charge must have been created before the policy commission went inactive

Producer Code > Policy Commission > Policy Period > Account > Charge

OR

Producer Code > Policy Commission > Item Commission > InvoiceItem > Charge

Account contact

GET /billing/v1/accounts/{accountId}/contacts/{contactId}

GET /billing/v1/accounts/{accountId}/contacts

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

GET /billing/v1/accounts/{accountId}/delinquency-processes/{delinquencyProcessId}

GET /billing/v1/accounts/{accountId}/delinquency-processes

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

GET /billing/v1/accounts/{accountId}/invoices

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

GET /billing/v1/producers/{producerId}/ab-money-rcvds

GET /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}

DELETE /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}

POST /billing/v1/producers/{producerId}/ab-money-rcvds

POST /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/modify

POST /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/execute

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 agencyCyclePayment object in the body.)

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

GET /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments

GET /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}

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

GET /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-payment-items

GET /producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-payment-items{agencyPaymentItemId}

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

GET /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-suspense-payment-items

GET /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-suspense-payment-items/{agencySuspPmntItemId}

POST /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-suspense-payment-items/{agencySuspPmntItemId}/release

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

GET /billing/v1/producers/{producerId}/agency-bill-cycles

GET /billing/v1/producers/{producerId}/agency-bill-cycles/{agencyBillCycleId}

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

GET /billing/v1/producers/{producerId}/agency-bill-payment-exceptions

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

GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}/policy-commissions/{policyCommissionId}/charge-commissions

GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}/policy-commissions/{policyCommissionId}/charge-commissions/{chargeCommissionId}

Callers can GET all charge commissions for policy commissions they have access to. ProducerCode > PolicyCommission > ChargeCommission
Charge invoice item

GET /billing/v1/charges/{chargeId}/invoice-items

GET /billing/v1/charges/{chargeId}/invoice-items/{invoiceItemId}

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

GET /billing/v1/charges/{chargeId}

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 PayerProducerCode field).

If the charge has an account as the payer, callers using the producer codes strategy can view claim charges in the following circumstances:
  • They have an active policy commission on the policy period for the claim
  • They have an active item commission
  • They have an inactive item commission with a commission amount greater than 0 on the policy period for the claim. Additionally, in this case, the charge must have been created before the policy commission went inactive

ProducerCode > BillingInstruction > Charge

OR

Producer Code > PolicyCommission > PolicyPeriod > Account > Charge

OR

ProducerCode > Policy Commission > ItemCommission > InvoiceItem > Charge

Disbursement

GET /billing/v1/disbursements/{disbursementId}

GET /billing/v1/disbursements

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/invoices/{invoiceId}

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

GET /billing/v1/invoices/{invoiceId}/invoice-items

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

GET /billing/v1/accounts/{accountId}/invoice-streams

GET /billing/v1/accounts/{accountId}/invoice-streams/{invoiceStreamId}

PATCH /billing/v1/accounts/{accountId}/invoice-streams/{invoiceStreamId}

POST /billing/v1/accounts/{accountId}/invoice-streams/{invoiceStreamId}/update-invoice-days

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 overridingPaymentInstrument.

ProducerCode > PolicyCommission > ItemCommission > Invoice > InvoiceStream
Item commission

GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}/policy-commissions/{policyCommissionId}/charge-commissions/{chargeCommissionId}/item-commissions/{itemCommissionId}

GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}/policy-commissions/{policyCommissionId}/charge-commissions/{chargeCommissionId}/item-commissions/

Callers can access item commissions for charge commissions they have access to. ProducerCode > PolicyCommission > ChargeCommission > ItemCommission
Policy

GET /billing/v1/accounts/{accountId}/policies

GET /billing/v1/accounts/{accountId}/policies/{policyId}

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

GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}/policy-commissions

GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}/policy-commissions/{policyCommissionId}

If the caller provides a producer code associated with a policy commission, they get access to the full policy commission. ProducerCode > PolicyCommission
Policy period

GET /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}

POST /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/change-payment-plan

Callers can access a restricted view of policy periods and change the policy period payment plan if they provide producer codes with:
  • An active policy commission on the policy period
  • An active item commission on any invoice item on any charge on the policy period
  • An inactive item commission with commissionAmount > 0 on any charges on the policy period

ProducerCode > PolicyCommission > PolicyPeriod

OR

ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge > PolicyPeriod

Policy period-level charge

GET /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/charges

GET /billing/v1/charges/{chargeId}

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:

  • Active policy commission on the charge’s policy period
  • An active item commission on any charge on the policy period
  • An inactive item commission with a commission amount greater than 0 on the charge's policy period. Additionally, in this case, the charge must have been created before the policy commission went inactive

ProducerCode > PolicyCommission > ItemCommission > InvoiceItem > Charge

OR

ProducerCode > PolicyCommission > PolicyPeriod > Policy > Account > Charge

Policy period contact

GET /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/contacts

GET /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/contacts/{contactId}

If the caller has access to the parent policy period, they get restricted access to all policy period contacts. ProducerCode > PolicyCommission > PolicyPeriod > PolicyPeriodContact
Producer

GET /billing/v1/producers/{producerId}

PATCH /billing/v1/producers/{producerId}

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: accountRep and defaultPaymentInstrument.

If the caller provides at least one of the producer’s producer codes, they get restricted access to the producer.

ProducerCode > Producer
Producer code

GET /billing/v1/producers/{producerId}/producer-codes

GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}

Callers can view producer codes that are included in the JWT. (Not relevant)
Producer contact

GET /billing/v1/producers/{producerId}/contacts

GET /billing/v1/producers/{producerId}/contacts/{contactId}

POST /billing/v1/producers/{producerId}/contacts

PATCH /billing/v1/producers/{producerId}/contacts/{contactId}

DELETE /billing/v1/producers/{producerId}/contacts/{contactId}

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: correspondenceTypes.

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

GET /billing/v1/producers/{producerId}/disbursements

Callers that provide any producer codes on the producer can access a restricted view of disbursements on that producer. ProducerCode > Producer > Disbursement
Producer invoice

GET /billing/v1/producers/{producerId}/invoices

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

GET /billing/v1/producers/{producerId}/payment-instruments

GET /billing/v1/producers/{producerId}/payment-instruments/{paymentInstrumentId}

POST /billing/v1/producers/{producerId}/payment-instruments

PATCH /billing/v1/producers/{producerId}/payment-instruments/{paymentInstrumentId}

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

GET /billing/v1/universal-payment-instruments

GET /billing/v1/universal-payment-instruments/{universalPaymentInstrumentId}

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

GET /admin/v1/agency-bill-plans

GET /admin/v1/agency-bill-plans/{agencyBillPlanId}

The caller has view access to the agency bill plans for all producers they have access to. ProducerCode > Producer > AgencyBillPlan
Billing plan

GET /admin/v1/billing-plans

GET /admin/v1/billing-plans/{billingPlanId}

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

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/charge-pattern-rates

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/charge-pattern-rates/{chargePatternRateId}

The caller has access to the charge pattern rates for the commission subplans they can access. ProducerCode > CommissionPlan > CommissionSubPlan > CommissionSubPlanChargePatternRate
Commission plan

GET /admin/v1/commission-plans

GET /admin/v1/commission-plans/{commissionPlanId}

The caller has access to the commission plans associated with the producer codes provided in the JWT. ProducerCode > CommissionPlan
Commission subplan

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}

The caller has access to commission subplans for the commission plans they can access. ProducerCode > CommissionPlan > CommissionSubPlan
Commissionable charge item

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/commissionable-charge-items

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/commissionable-charge-items/{commissionableChargeItemId}

The caller has access to the commissionable charge items for the commission subplans they can access. ProducerCode > CommissionPlan > CommissionSubPlan > CommissionSubPlanChargePatternRate
Delinquency event

GET /admin/v1/delinquency-plans/{delinquencyPlanId}/reasons/{delinquencyPlanReasonId}/events

GET /admin/v1/delinquency-plans/{delinquencyPlanId}/reasons/{delinquencyPlanReasonId}/events/{delinquencyPlanEventId}

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

GET /admin/v1/delinquency-plans GET /admin/v1/delinquency-plans/{delinquencyPlanId}

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

GET /admin/v1/delinquency-plans/{delinquencyPlanId}/reasons

GET /admin/v1/delinquency-plans/{delinquencyPlanId}/reasons/{delinquencyPlanReasonId}

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

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/incentives

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/incentives/{incentiveId}

The caller has access to the incentives for the commission subplans they can access. ProducerCode > CommissionPlan > CommissionSubPlan > Incentive
Payment Plan

GET /admin/v1/payment-plans

GET /admin/v1/payment-plans/{paymentPlanId}

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

GET /admin/v1/payment-plans/{paymentPlanId}/overrides

GET /admin/v1/payment-plans/{paymentPlanId}/overrides/{paymentPlanOverrideId}

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

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/section-rates

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/section-rates/{sectionRateId}

The caller has access to the section rates for the commission subplans they can access. ProducerCode > CommissionPlan > CommissionSubPlan > CommissionSubPlanSectionRate
Subplan rate

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/commission-sub-plan-rates

GET /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/commission-sub-plan-rates/{commissionSubPlanRateId}

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.

There are several different types of producer transfers:
  • 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 following table describes whether charges are viewable for producer codes following a producer transfer. Note the following:
  • 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