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 |
For each
|
paymentPlan |
An object specifying the policy’s payment plan. |
|
policy |
An object containing optional information about the policy. |
No required fields |
policyPeriod |
An object containing information on the policy period. |
|
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.
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.
primaryNamedInsuredContact
object:- The
contactSubtype
field (can bePerson
orCompany
) - 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
- If it is a person, the only required additional field is
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.
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
, andreferrer
.
"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 toAgencyBill
. - In the
producerCodesAndRoles
field, there must be a producer code with a role ofprimary
. - 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
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"
}
}