Creating an account

To create a new account through Cloud API, use the following endpoint:

POST /billing/v1/accounts

Minimum creation criteria

To create an account, the minimum amount of information you must provide is listed in the following table.


Field	Value	Comments
Basic information
`billDateOrDueDateBilling`	A value from the `BillDateOrDueDateBilling` typelist, such as `DueDateBilling`
`billingLevel`	A value from the `BillingLevel` typelist, such as `PolicyDesignatedUnapplied`
`currency`	A value from the `Currency` typelist, such as `USD`
Plans
`billingPlan`	The id of an existing billing plan
`delinquencyPlan`	The id of an existing delinquency plan
`paymentAllocationPlan`	The id of an existing payment allocation plan
Invoice stream information
`everyOtherWeekInvoiceAnchorDate`	A date
`firstTwicePerMonthInvoiceDayOfMonth`	An integer
`invoiceDayOfMonth`	An integer
`invoiceDayOfWeek`	A value from the `DayOfWeek`, such as `Friday`
`secondTwicePerMonthInvoiceDayOfMonth`	An integer

The accountNumber field is required by the database. But, there is an account number generator plugin that provides a default value. If you wish to use the value generated by the plugin, omit the accountNumber field from the POST.

Plans required for a new account

To create an account, you must reference a billing plan, delinquency plan, and payment allocation plan for the account. You cannot use request inclusion to create an account and a billing plan, delinquency plan, or payment allocation plan in the same call. These plans must exist before the call that creates the account, and the call that creates the account must reference existing plans.

Differences between the user interface and Cloud API

The BillingCenter user interface has a New Account screen where you can create an account manually. There are differences between the minimum criteria for that screen and for the POST /accounts endpoint.

The New Account screen requires the values in the following table. However, these values are not enforced at the database layer and therefore they are not enforced by Cloud API.


User interface field	Data model field	Cloud API default for this field
Type	`AccountType`	Insured
Send Invoices By	`InvoiceDeliveryType`	null
Default Payment Instrument	`DefaultPaymentInstrument`	Responsive

The New Account screen requires an account to have exactly one contact with the Primary Payer flag. Accounts created from the POST /accounts endpoint are not required to have any contacts.

Creating an account example payload

The following payload creates a new account. Note that when specifying plans, the plan displayName fields are not required and are ignored. These fields have been included below to clarify the business intention of the payload.

POST /billing/v1/accounts

{
  "data": {
    "attributes": {
        "accountNumber": "Cloud API Account 1",
        "billDateOrDueDateBilling": {
            "code": "BillDateBilling"
        },
        "billingLevel": {
            "code": "PolicyDesignatedUnapplied"
        },
        "billingPlan": {
            "displayName": "Standard Mail",
            "id": "bc:S7ESqf3xS94SUQCSAMTUb"
        },
        "currency": {
            "code": "usd"
        },
        "delinquencyPlan": {
            "displayName": "Standard Delinquency Plan",
            "id": "bc:S-JLxwyYClKzbwEfswJ9Q"
        },
        "everyOtherWeekInvoiceAnchorDate": "2022-08-09",
        "firstTwicePerMonthInvoiceDayOfMonth": 1,
        "invoiceDayOfMonth": 1,
        "invoiceDayOfWeek": {
            "code": "Friday"
        },
        "paymentAllocationPlan": {
            "displayName": "Default Payment Allocation Plan",
            "id": "cash_plan:1"
        },
        "secondTwicePerMonthInvoiceDayOfMonth": 15
    }
  }
}

Child objects for an account

An account can also have several types of child objects. They are summarized in the following table.


Object type	More information
Account contacts	Account contacts
Invoices	Invoices