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
(typicallyPerson
orCompany
)- For the
Person
subtype, you must also specifylastName
(firstName
?) - For the
Company
subtype, you must also specifycompanyName
- For the
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"
}
]
}
}
}