Creating an account

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

  • POST /account/v1/accounts

Minimum creation criteria

To create an account, the minimum amount of information you must provide is:

  • The 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 results of each approach are 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 (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 a location, identified as address or some portion of an address, that is the primary location 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 contact 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 results of each approach are the same.

In either approach, you must by default 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 "specific" the location 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 required for a complete address is a street address, city, state or province, and postal code.
    • This is the flag's default value. If the nonSpecific flag is not specified, then it is considered specific and must be 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 false.

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.

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 must include a producerCodes array with exactly one producer code. For example:

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

Creating an account example payload

The following payload creates a new account using the initialAccountHolder and initialPrimaryLocation attributes.

POST /account/v1/accounts

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