Accounts

In PolicyCenter, an account is associated with an individual or company, and is typically created when quoting a policy for a new prospect. At a minimum, an account must have the name of the account holder, basic location information for the account holder, and information about the producer associated with the account.

Creating an account

To create a new account in PolicyCenter, a caller can use the POST /account/v1/accounts endpoint from the Account API. When creating an account, the caller must provide the following data in the request payload:

An account holder
A primary location
A producer code

A caller can provide additional account information in the request payload, as defined by the schema for the Account resource.

Name clearance

Name clearance is the process of checking against one or more producer/account databases to ensure that a person or company is not an existing account in PolicyCenter. Because name clearance requirements differ across insurers, it is not implemented in the system APIs directly. Implementors of services that require name clearance can configure that functionality in their own code.

Account holder

The account holder indicates the primary contact that will be associated with the account. An account holder can be an individual or a company, and this information must be specified in the request. Additionally, the request must also include a name and address for the account holder.

On account creation, the account status is set to Pending. This indicates that the account exists but that there are no policies associated with it.

Calls to POST /account/v1/accounts are not idempotent. A caller can create multiple new accounts for the same person or company.

Setting an account holder

To set the account holder, the caller can use the initialAccountHolder attribute in the request payload. Alternatively, the caller can use the accountHolder attribute in tandem with an include containing an AccountContact resource. This latter approach involves request inclusion. For more information, see Request inclusion.

When setting an account holder, the caller must provide values for the contactSubtype, primaryAddress.addressLine1, primaryAddress.city, primaryAddress.state, and primaryAddress.postalCode fields. If the account is for an individual, then the caller must also include the firstName and lastName fields. If the account is for a company, then the caller must include the companyName field.

In the following example, the necessary fields for an individual account holder are attached to 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"
          }
        }
      },
      . . .
    }
  }
}

The next example demonstrates how to set the account holder for the same individual, using the accountHolder attribute with an AccountContact include:

{
  "data": {
    "attributes": {
      "accountHolder": {
        "refid": "newperson"
      },
      . . .
    }
  },
  "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": "newperson",
        "uri": "/account/v1/accounts/this/contacts"
      }
    ]
  }
}

The next example illustrates how to set the account holder for a company, using the initialAccountHolder attribute:

{
  "data": {
    "attributes": {
      "initialAccountHolder": {
        "contactSubtype": "Company",
        "companyName": "Preston, Inc.",
        "primaryAddress": {
          "addressLine1": "2850 S. Delaware St.",
          "city": "San Mateo",
          "postalCode": "94403",
          "state": {
            "code": "CA"
          }
        }
      },
      . . .
    }
  }
}

Primary location

The primary location indicates the primary address that will be associated with the account.

To set the primary account location, the caller can use the initialPrimaryLocation attribute in the request payload. Alternatively, the caller can use the primaryLocation attribute in tandem with an include containing an AccountLocation resource. This latter approach involves request inclusion. For more information, see Request inclusion.

When creating an account, the account location can be specific or non-specific. A specific account location must include the street address, city, state or province, and postal code. A non-specific account location must include the state or province at minimum, as this is necessary to determine several locale-related constraints for the account.

Setting a specific account location

When setting a specific location, the caller must provide values for the addressLine1, city, state, and postalCode fields. In the following example, these fields are attached to the initialPrimaryLocation attribute:

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

The next example accomplishes the same thing with request inclusion, using the primaryLocation attribute with an AccountLocation include:

{
  "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"
      }
    ]
  }
}

Setting a non-specific account location

When setting a non-specific location, the caller must provide values for the state and nonSpecific fields. In the following example, these fields are attached to the initialPrimaryLocation attribute:

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

The next example accomplishes the same thing with request inclusion, using the primaryLocation attribute with an AccountLocation include:

{
  "data": {
    "attributes": {
      . . .
      "primaryLocation": {
        "refid": "newlocation"
      }
    }
  },
  "included": {
    "AccountLocation": [
      {
        "attributes": {
          "nonSpecific": true,
          "state": {
            "code": "CA"
          }
        },
        "method": "post",
        "refid": "newlocation",
        "uri": "/account/v1/accounts/this/locations"
      }
    ]
  }
}

Producer code

At creation time, an account must be associated with one producer code. This is a PolicyCenter requirement, and cannot be circumvented by the system APIs.

The request payload must include a producerCodes attribute. This is an array of one object that contains an id field for the producer code:

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

Example: Creating an account

The following code sample depicts a complete request payload that can be POSTed to the /account/v1/accounts endpoint. The example includes the optional properties preferredCoverageCurrency and preferredSettlementCurrency. The account holder and primary location properties are applied through request inclusion. For details on request inclusion, see Request inclusion.

Request payload for creating a new account using request inclusion

{
  "data": {
    "attributes": {
      "accountHolder": {
        "refid": "newperson"
      },
      "organizationType": {
        "code": "individual"
      },
      "preferredCoverageCurrency": {
        "code": "USD"
      },
      "preferredSettlementCurrency": {
        "code": "USD"
      },
      "primaryLocation": {
        "refid": "newloc"
      },
      "producerCodes": [
        {
          "id": "pc:6"
        }
      ]
    }
  },
  "included": {
    "AccountContact": [
      {
        "attributes": {
          "contactSubtype": "Person",
          "firstName": "Bill",
          "lastName": "Preston",
          "primaryAddress": {
            "addressLine1": "2850 S Delaware St #400",
            "city": "San Mateo",
            "postalCode": "94403",
            "state": {
              "code": "CA"
            }
          }
        },
        "method": "post",
        "refid": "newperson",
        "uri": "/account/v1/accounts/this/contacts"
      }
    ],
    "AccountLocation": [
      {
        "attributes": {
          "locationCode": "0001",
          "locationName": "Location 0001",
          "nonSpecific": true,
          "postalCode": "94403",
          "state": {
            "code": "CA"
          }
        },
        "method": "post",
        "refid": "newloc",
        "uri": "/account/v1/accounts/this/locations"
      }
    ]
  }
}

Account search

Through the Account API, a caller can use the /acccount/v1/search/accounts endpoint to search for accounts. To execute a search, a caller can submit a POST request to the search endpoint. The request payload must contain one of the following items:

accountNumber: Account number
companyName: Complete company name. When searching by company name, do not include personal name data.
firstName and lastName: Complete first name and last name of the account holder. When searching by account holder name, both fields must be included in the request. When searching by personal name, do not include company name data.
organization.id: Company identification number
phoneNumber: Telephone number
producerCode.id: Producer code
taxId: Tax identification number

Note:

When searching by personal name or company name, the complete name must be entered. Partial matching is not supported. Also, searching by address is not supported.

The following code block is a request body for a search based on a personal name:

{
  "data": {
    "attributes": {
      "firstName": "Ray",
      "lastName": "Newton"
    }
  }
}

A successful search request returns an array of account objects. For example, a search using the request body above returns the following:

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "accountHolder": {
                    "displayName": "Ray Newton",
                    "id": "test_pp:2"
                },
                "accountNumber": "C000143542",
                "accountStatus": {
                    "code": "Active",
                    "name": "Active"
                },
                "businessOperationsDescription": "business description",
                "createdDate": "2021-04-10T22:12:13.688Z",
                "frozen": false,
                "id": "pc:2",
                "industryCode": {
                    "code": "0740",
                    "description": "Veterinarians / Veterinarian / Veterinary Services",
                    "id": "SIC:0740"
                },
                "numberOfContacts": "8",
                "organizationType": {
                    "code": "commonownership",
                    "name": "Common ownership"
                },
                "preferredCoverageCurrency": {
                    "code": "usd",
                    "name": "USD"
                },
                "preferredSettlementCurrency": {
                    "code": "usd",
                    "name": "USD"
                },
                "primaryLanguage": {
                    "code": "en_US",
                    "name": "English (US)"
                },
                "primaryLocale": {
                    "code": "en_US",
                    "name": "United States (English)"
                },
                "primaryLocation": {
                    "displayName": "4: 1253 Paloma Ave, Arcadia, CA",
                    "id": "pc:749",
                    "type": "AccountLocation",
                    "uri": "/account/v1/accounts/pc:2/locations/pc:749"
                },
                "producerCodes": [
                    {
                        "displayName": "100-002541",
                        "id": "pc:6"
                    }
                ]
            },
            . . .
}

The search endpoint also supports certain locale-specific fields:

companyNameKanji: Complete company name, in Japanese
firstNameKanji: Complete first name, in Japanese. Can be used in combination with firstName or lastNameKanji.
lastNameKanji: Complete last name, in Japanese. Can be used in combination with lastName or firstNameKanji.
particle: Particle used in account holder's name (matching the particle property of an AccountContact resource)

The following code block is a request body for a search based on first name and first name in Japanese:

{
  "data": {
    "attributes": {
      "firstNameKanji": "太郎",
      "firstName": "Taro"
    }
  }
}