Issuing policies

Use the following endpoint to issue policies in BillingCenter:

  • POST billing/v1/accounts/{accountId}/issuances

Minimum creation criteria

The policy issuance request object consists of several required objects and one array. Some of these top-level entities have required fields. The following table details these entities and their required fields:

Object Description Required fields
charges

An array of charge objects.

For each charge object:

  • amount
  • chargePattern
paymentPlan

An object specifying the policy’s payment plan.
  • id
policy

An object containing optional information about the policy.

No required fields
policyPeriod

An object containing information on the policy period.
  • effectiveDate
  • expirationDate
  • policyNumber

Minimal policy issuance request

The following request provides an example of issuing a minimal policy on account bc:101

Command

POST /billing/v1/accounts/bc:101/issuances

Request body

{
    "data": {
        "attributes": {
            "charges": [
                {
                    "amount": {
                        "amount": "1200",
                        "currency": "USD"
                    },
                    "chargePattern": {
                        "id": "default_data:1",
                    }
                },
                {
                    "amount": {
                        "amount": "60",
                        "currency": "USD"
                    },
                    "chargePattern": {
                        "id": "default_data:6",
                    }
                }
            ],
            "paymentPlan": {
                "id": "bc:SseFjlFaE9xxBLBG1ZRNR"
            },
            "policy": {},
            "policyPeriod": {
                "effectiveDate": "2023-12-11",
                "expirationDate": "2024-12-11",
                "policyNumber": "PA-234553"
            }
        }
    }
}

This request performs the following:

  • Creates a personal auto policy with the policy number PA-234553
    • This is a direct bill policy, because this is the default billing method
  • Creates a policy period on that policy
  • Sets the payment plan to an existing payment plan
  • Creates two charges on the policy period: one $1200 premium charge and one $60 tax charge. The charge pattern is identified by the id.
Note: In this example, there is no need to specify any fields for the policy itself. But the policy object is always required, even when there are no fields to specify. This is why the payload includes an empty policy object.

Specifying additional information

When specifying policy and policy period details, take note of the following guidelines.

Overriding payer accounts and invoice streams - Invoice streams must be on the same account as the payer account. If you add an overriding payer account, the invoice stream will automatically be set to this payer’s default invoice stream. This can be set on either the policy period or on specific charges.

Policy number - The policy number for a newly issued policy must be unique.

Currency - Payment plans and delinquency plans have arrays of supported currencies. The payer account’s currency must be included in those arrays.

In a mono-currency instance of BillingCenter, any monetary amount specified in a request must have the same currency as the payer account. This includes charges, deposit requirements, and other monetary information provided in the policyPeriod object. Additionally, the overriding payer account and the account that owns the policy must both have the same currency.

In a multicurrency instance of BillingCenter, the currency of a charge can be different than the account's currency. However, as of this release, Cloud API does not support billing requests where the currency of any charge is different than the account's currency. For billing requests submitted through Cloud API, all charges must have the same currency as the associated account

Charge breakdowns - As of this release, Cloud API does not support adding charge breakdown information when issuing a policy.

Contacts - When issuing a policy, you can create a primary insured contact using the primaryNamedInsuredContact field. This can be either a person or a company. Other contact types, such as places, are not used in BillingCenter.

There are two required fields in the primaryNamedInsuredContact object:
  • The contactSubtype field (can be Person or Company)
  • The contact name
    • If it is a person, the only required additional field is lastName
    • If it is a company, the only required additional field is Company

Sending the primaryNamedInsuredContact field creates a contact with a role of Primary Insured. The contact that is created always has the role of Primary Insured, and you can specify an additional role for the contact using the roles array. In the base configuration, the only additional role you can add is Additional Named Insured (code: additionalnamedins). If you specify this role on the contact, it adds it as an additional role while keeping the Primary Insured role.

Billing method - Specify the policy's billing method using the billingMethod field in the policyPeriod object. There are two supported billing methods when issuing policies through Cloud API: DirectBill and AgencyBill. The default is DirectBill. Find more information about issuing agency bill policies in the section below.

Producer codes and roles - The field ProducerCodesAndRoles can be used to add producers to the policy. This field is an array of objects containing producer codes and roles.
  • The producer code is a unique code that assigns a producer a commission plan, which is referenced by its id.
  • The role is the role the producer has on the policy. In the base configuration of BillingCenter, the only roles are primary, secondary, and referrer.
For example, the field below would be included in the issuance:
"producerCodesAndRoles": [
    {
        "producerCode": {
            "id": "bc:SHPa4iv-HepnMPr6JikP_"
        },
        "role": {
            "code": "primary"
        }
    },
    {
        "producerCode": {
            "id": "bc:ScqJTr8bwlIGeCeNqEA3m"
        },
        "role": {
            "code": "secondary"
        }  
    }
]

Issuing agency bill policies

You can issue an an agency bill policy through Cloud API. The issuance must contain the following features:

  • The billingMethod field must be set to AgencyBill.
  • In the producerCodesAndRoles field, there must be a producer code with a role of primary.
  • The primary producer must have an agency bill plan.

If additional producers with non-primary roles are included in the producerCodesAndRoles object, they receive commission as if it were a direct bill policy.

The issuance response object

The minimal POST request provided above returns the following response object.
POST /billing/v1/accounts/bc:101/issuances

{
    "data": {
        "attributes": {
            "charges": [
                {
                    "amount": {
                        "amount": "1200.00",
                        "currency": "usd"
                    },
                    "chargeDate": "2023-12-12T17:29:05.022Z",
                    "chargePattern": {
                        "displayName": "Premium",
                        "id": "default_data:1",
                        "type": "ChargePattern",
                        "uri": "/admin/v1/charge-patterns/default_data:1"
                    },
                    "holdStatus": {
                        "code": "none",
                        "name": "Not Held"
                    },
                    "id": "bc:SFy0AE8LdXyShiK08inYY",
                    "reversed": false,
                    "skipInvoiceItemCreation": false,
                    "totalInstallments": 9
                },
                {
                    "amount": {
                        "amount": "60.00",
                        "currency": "usd"
                    },
                    "chargeDate": "2023-12-12T17:29:05.022Z",
                    "chargePattern": {
                        "displayName": "Taxes",
                        "id": "default_data:6",
                        "type": "ChargePattern",
                        "uri": "/admin/v1/charge-patterns/default_data:6"
                    },
                    "holdStatus": {
                        "code": "none",
                        "name": "Not Held"
                    },
                    "id": "bc:SakMlRBrLNvF0Crvj2Mrl",
                    "reversed": false,
                    "skipInvoiceItemCreation": false,
                    "totalInstallments": 0
                }
            ],
            "createTime": "2023-12-12T17:29:05.022Z",
            "executed": true,
            "id": "bc:SZVcFGJg56XPQPrtq8HUG",
            "paymentPlan": {
                "displayName": "A Monthly 10% Down, 9 Max installments",
                "id": "bc:SseFjlFaE9xxBLBG1ZRNR",
                "type": "PaymentPlan",
                "uri": "/admin/v1/payment-plans/bc:SseFjlFaE9xxBLBG1ZRNR"
            },
            "policy": {
                "createTime": "2023-12-12T17:29:05.022Z",
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "displayName": "PA-234553",
                "doNotArchive": false,
                "id": "bc:S6UbABC8vyTq2lKgu3GVK"
            },
            "policyPeriod": {
                "assignedRisk": false,
                "billingMethod": {
                    "code": "DirectBill",
                    "name": "Direct Bill"
                },
                "boundDate": "2023-12-11",
                "cancelStatus": {
                    "code": "open",
                    "name": "Open"
                },
                "chargeHeld": false,
                "closureStatus": {
                    "code": "open",
                    "name": "Open"
                },
                "confirmationNotificationState": {
                    "code": "DoNotNotify",
                    "name": "Do Not Notify"
                },
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "effectiveDate": "2023-12-11",
                "eligibleForFullPayDiscount": false,
                "equityBuffer": 30,
                "equityWarningsEnabled": true,
                "expirationDate": "2024-12-11",
                "fullPayDiscountEvaluated": false,
                "heldForInvoiceSending": false,
                "holdInvoicingWhenDelinquent": false,
                "id": "bc:S-r07gO0hbKuQwcUoeAWf",
                "paymentDistributionEnabled": true,
                "paymentPlan": {
                    "displayName": "A Monthly 10% Down, 9 Max installments",
                    "id": "bc:SseFjlFaE9xxBLBG1ZRNR",
                    "type": "PaymentPlan",
                    "uri": "/admin/v1/payment-plans/bc:SseFjlFaE9xxBLBG1ZRNR"
                },
                "pendingRemainingBalanceFix": false,
                "policyNumber": "PA-234553",
                "policyNumberLong": "PA-234553-1",
                "retrieved": false,
                "returnPremiumPlan": {
                    "displayName": "Default Return Premium Plan",
                    "id": "ret_premium_plan:1",
                    "type": "ReturnPremiumPlan",
                    "uri": "/admin/v1/return-premium-plans/ret_premium_plan:1"
                },
                "termConfirmed": true,
                "termNumber": 1,
                "westernMethod": false
            }
        },
        "checksum": "0"
    }
}