Creating an account

To create a new account, use the following endpoint:

POST /account/v1/accounts

Minimum creation criteria

The minimum amount of information you must provide is:

An account holder
A primary location
A producer code

The following sections cover these pieces of information in detail. For an example of how to create an account, see Creating an account example payload.

The account holder

The account holder is the primary contact associated with the account. This information is stored in PolicyCenter as an AccountContact.

There are two ways you can specify the account holder in a POST /accounts payload:

Using the initialAccountHolder attribute
Using the accountHolder attribute to reference a contact created through request inclusion

The only difference between these two approaches is the way the information is specified. The first approach specifies the initial account holder in the main attributes section, and the second specifies it using request inclusion. Otherwise, the result of each approach is the same.

In either approach, you must specify the following information for the account holder:

contactSubtype (typically Person or Company)
- For the Person subtype, you must also specify lastName and firstName
- For the Company subtype, you must also specify companyName
primaryAddress, which must include:
- addressLine1
- city
- state
- postalCode

Using the `initialAccountHolder` attribute

The initialAccountHolder attribute lets you specify the account holder information in the attributes section of the request payload. For example, the following snippet specifies the account holder using the initialAccountHolder attribute:

{
  "data": {
    "attributes": {
      "initialAccountHolder": {
        "contactSubtype": "Person",
        "firstName": "Bill",
        "lastName": "Preston",
        "primaryAddress": {
          "addressLine1": "2850 S. Delaware St.",
          "city": "San Mateo",
          "postalCode": "94403",
          "state": {
            "code": "CA"
          }
        }
      },
...

Using the `accountHolder` attribute

The accountHolder attribute requires you to specify the AccountContact information in the included section of the payload, as opposed to in the attributes section. You then reference the contact using a refid. For example, the following snippet specifies the account holder using the accountHolder attribute:

{
  "data": {
    "attributes": {
      "accountHolder": {
        "refid": "BillPreston"
        },
      ...
    },
  "included": {
    "AccountContact": [
      {
        "attributes": {
          "contactSubtype": "Person",
          "firstName": "Bill",
          "lastName": "Preston",
          "primaryAddress": {
            "addressLine1": "2850 S. Delaware St.",
            "city": "San Mateo",
            "postalCode": "94403",
            "state": {
              "code": "CA"
            }
          }
        },
        "method": "post",
        "refid": "BillPreston",
        "uri": "/account/v1/accounts/this/contacts"
      }
    ]
  }
}

The primary location

The primary location is the primary address associated with the account. This information is stored in PolicyCenter as an AccountLocation.

There are two ways you can specify the account location in a POST /accounts payload:

Using the initialPrimaryLocation attribute
Using the primaryLocation attribute to reference a location created through request inclusion

The only difference between these two approaches is the way the information is specified. The first approach specifies the primary location in the main attributes section, and the second specifies it using request inclusion. Otherwise, the result of each approach is the same.

In either approach, by default, you must specify the following information for the primary location:

addressLine1
city
state
postalCode

Using the `initialPrimaryLocation` attribute

The initialprimaryLocation attribute lets you specify the primary location information in the attributes section of the request payload. For example, the following snippet specifies the primary location using the initialPrimaryLocation attribute:

{
  "data": {
    "attributes": {
      "initialPrimaryLocation": {
        "addressLine1": "2850 S. Delaware St.",
        "city": "San Mateo",
        "postalCode": "94403",
        "state": {
          "code": "CA"
        }
      },
...

Using the `primaryLocation` attribute

The primaryLocation attribute requires you to specify the AccountLocation information in the included section of the payload, as opposed to in the attributes section. For example, the following snippet specifies the primary location using the primaryLocation attribute:

{
  "data": {
    "attributes": {
      "primaryLocation": {
        "refid": "newlocation"
        },
      ...
    },
  "included": {
    "AccountLocation": [
      {
        "attributes": {
          "addressLine1": "2850 S. Delaware St.",
          "city": "San Mateo",
          "postalCode": "94403",
          "state": {
            "code": "CA"
          }
        },
        "method": "post",
        "refid": "newlocation",
        "uri": "/account/v1/accounts/this/locations"
      }
    ]
  }
}

Non-specific locations

All locations, including an account's primary location, have a nonSpecific flag that indicates how complete the location information is. This flag defaults to false.

If the flag is set to false, the location is considered to be specific.
- A specific location is a location that includes a complete address. The definition of a complete address can vary by locale. In North America, the minimum requirements for a complete address are a street address, city, state or province, and postal code.
- This is the flag's default value. When the nonSpecific flag is not specified, the location is considered to be specific and must consist of a complete address.
If the flag is set to true, the location is considered to be non-specific.
- A non-specific location is a location that includes a state or province, as this is required to determine locale-related constraints. But otherwise, it is not required to include any additional address information.
- For a location to be considered non-specific, the nonSpecific flag must be explicitly set to true.

For example, the following snippet specifies the primary location using the initialPrimaryLocation attribute and a non-specific address:

{
  "data": {
    "attributes": {
      "initialPrimaryLocation": {
        "nonSpecific": true,
        "state": {
          "code": "CA"
        }
...

The producer code

Every new account must be associated with exactly one producer code. This can be done in one of two ways. Either you can supply a producer code in the request body when you create the account, or you can set up a default producer code.

Provide a producer code in the REST API request

To provide a producer code in the request body when you create an account, you must first retrieve the producer code, then create the account.

Retrieving producer codes

There are two endpoints you can use to retrieve producer codes, one in the Account API and one in the Admin API. These endpoints are:

GET /account/v1/producer-codes
GET /admin/v1/producer-codes

The Admin API version returns all producer codes, regardless of their status. The Account API version returns only the producer codes available to the caller. The Account API version omits producer codes that the caller cannot use (such as producer codes that are inactive or that are not available to the specific caller).

When you execute either endpoint, the payload for each producer code looks similar to the following example.

{
    "attributes": {
        "branch": {
            "branchCode": "301",
            "displayName": "Minneapolis Branch UW",
            "id": "pc:Sk46AxgTMK1O7s6659Ats"
        },
        "code": "301-008578",
        "description": "ACV Property Insurance",
        "displayName": "301-008578",
        "id": "pc:16",
        "organization": {
            "displayName": "ACV Property Insurance",
            "id": "pc:4",
            "type": "Organization",
            "uri": "/admin/v1/organizations/pc:4"
        },
        "producerStatus": {
            "code": "Active",
            "name": "Active"
        }
    }

For more information on working with producer codes through Cloud API, see Producer codes

Specifying producer codes

When creating an account, the request payload can include a producerCodes array with exactly one producer code. For example:

{
  "data": {
    "attributes": {
      "producerCodes": [
        {
          "id": "pc:16"
        }
      ]
...

The producerCodes array is required in the request if either of the following is true:

There is no default producer code defined
There is a default producer code defined but you want the producer code to be different from the default when the account is created

Set a default producer code

A producer code is required for an account to be created. In the base configuration the existence of a producer code in the account creation request is validated programmatically. If there is no producer code in the request, PolicyCenter runs the getDefaultProducerCode method to check for a default producer code. If a default is found, that value is used in creating the account. If no producer code is found in the request and no default is found, Cloud API sends an error response.

The getDefaultProducerCode method is defined in AccountsCoreResoure.gs. To set a default producer code, override this method in the AccountsExtResource.gs extension file, as shown here:

class AccountsExtResource extends AccountsCoreResource {

  override function getDefaultProducerCode(attributes : DataAttributes) : ProducerCode {

    // retrieve and return a default producer code

  }
}

The default value will be applied to all new accounts that are created without specifying a producer code. If a producer code is specified in the account creation request, the default is ignored.