Appearance
V3 Upgrade Guide
Client Sync Workflow
The basic flow of GetAgencies -> Get Changed Clients -> Get Client/Get Clients is unchanged.
Change Detection
The v1.8 Client Hashes have been replaced by modified timestamps in v3. The Client Detail Modified timestamp reflects the latest update to any part of the client. Additionally, each Person, Policy, Claim, and Contact has an individual Modified timestamp representing the last update to that record.
Upgrade Checklist
This is a high-level list of tasks that will help you upgrade from V1 to V3.0. Continue reading for more details about individual changes to the client model.
- Include version query parameter in all API requests. (version = 3.0)
- Optionally prepare to consume the new LegacyId property. This property will have the same value as the Id property from the V1 API. You may use this property to help map the new GUID Ids to your existing data. Be aware that once an agency upgrades to HawkSoft 6, new items will not have a LegacyId value, as there is no pre-existing data to map to. Do not rely on this field for identifying records beyond the initial upgrade process.
Client
Id
Id has been renamed to ClientNumber. The value is unchanged.
JSON
json
// v1
{
"id": 10,
...
}
// v3
{
"clientNumber": 10,
...
}// v1
{
"id": 10,
...
}
// v3
{
"clientNumber": 10,
...
}AllowCrossSell
AllowCrossSell has been moved to the Client Details object.
JSON
json
// v1
{
"id": 10,
"allowCrossSell": false,
...
}
// v3
{
"clientNumber": 10,
"details": {
"allowCrossSell": false,
...
},
...
}// v1
{
"id": 10,
"allowCrossSell": false,
...
}
// v3
{
"clientNumber": 10,
"details": {
"allowCrossSell": false,
...
},
...
}ClientType
ClientType has been moved to the Client Details object.
JSON
json
// v1
{
"id": 0,
"clientType": "Customer",
...
}
// v3
{
"id": 0,
"details": {
"clientType": "Customer",
...
},
...
}// v1
{
"id": 0,
"clientType": "Customer",
...
}
// v3
{
"id": 0,
"details": {
"clientType": "Customer",
...
},
...
}ContactInfoLastUpdated
Moved to the Client Details object.
CustomClientId
Moved to the Client Details object.
DoNotMarket
Moved to the Client Details object.
IsBusiness
Removed. See BusinessType on the Client Details object. BusinessType: None is equivalent to IsBusiness: false. Any other BusinessType value is equivalent to IsBusiness: true.
IsActive
Removed. See Status on the Client Details object. Status: Active is equivalent to IsActive: true. Any other Status value is equivalent to IsActive: false.
IsArchived
Removed. The API does not return Archived clients.
IsCommercial
Moved to the Client Details object.
IsDeadFile
Removed. See Status on the Client Details object. Status: DeadFile is equivalent to IsDeadFile: true. Any other Status value is equivalent to IsDeadFile: false.
IsLead
Removed. See Status on the Client Details object. Status: Lead is equivalent to IsLead: true. Any other Status value is equivalent to IsLead: false.
IsLifeHealth
Moved to the Client Details object.
IsPersonal
Moved to the Client Details object.
IsProspect
Removed. See Status on the Client Details object. Status: Prospect is equivalent to IsProspect: true Any other Status value is equivalent to IsProspect: false.
OfficeId
Moved to the Client Details object.
Source
Moved to the Client Details object.
Addresses
Removed. See MailingAddress, PhysicalAddress, and PhysicalAtSince on the Client Detais object.
A V1 Address with Type: Mailing maps to Details.MailingAddress.
A V1 Address with Type: Physical maps to Details.PhysicalAddress, and Address.AtSince maps to Details.PhysicalAtSince.
Both Addresses are optional. A client may have neither, one, or both.
Mailing Address
json
// v1
{
"id": 0,
...,
"addresses": [
{
"addressType": "Mailing",
"atSince": null,
"city": "Seattle",
"country": "US",
"line1": "325 5th Ave N",
"line2": "#101",
"state": "WA",
"zipCode": "98109"
}
]
}
// v3
{
"details": {
"mailingAddress": {
"address1": "325 5th Ave N",
"address2": "#101",
"city": "Seattle",
"state": "WA",
"zip": "98109",
"countryCode": "US",
"county": "King"
},
"physicalAddress": null
}
}// v1
{
"id": 0,
...,
"addresses": [
{
"addressType": "Mailing",
"atSince": null,
"city": "Seattle",
"country": "US",
"line1": "325 5th Ave N",
"line2": "#101",
"state": "WA",
"zipCode": "98109"
}
]
}
// v3
{
"details": {
"mailingAddress": {
"address1": "325 5th Ave N",
"address2": "#101",
"city": "Seattle",
"state": "WA",
"zip": "98109",
"countryCode": "US",
"county": "King"
},
"physicalAddress": null
}
}Physical Address
json
// v1
{
"id": 0,
...,
"addresses": [
{
"addressType": "Physical",
"atSince": "2000-01-01",
"city": "Seattle",
"country": "US",
"line1": "325 5th Ave N",
"line2": "#101",
"state": "WA",
"zipCode": "98109"
}
]
}
// v3
{
"details": {
"mailingAddress": null,
"physicalAddress": {
"address1": "325 5th Ave N",
"address2": "#101",
"city": "Seattle",
"state": "WA",
"zip": "98109",
"countryCode": "US",
"county": "King"
},
"phsyicalAtSince": "2000-01-01"
}
}// v1
{
"id": 0,
...,
"addresses": [
{
"addressType": "Physical",
"atSince": "2000-01-01",
"city": "Seattle",
"country": "US",
"line1": "325 5th Ave N",
"line2": "#101",
"state": "WA",
"zipCode": "98109"
}
]
}
// v3
{
"details": {
"mailingAddress": null,
"physicalAddress": {
"address1": "325 5th Ave N",
"address2": "#101",
"city": "Seattle",
"state": "WA",
"zip": "98109",
"countryCode": "US",
"county": "King"
},
"phsyicalAtSince": "2000-01-01"
}
}BusinessProfiles
Removed. A client will never have more than one BusinessProfile, and business information has been moved to the Client Details object. A V3 Client with Details.BusinessType: None is equivalent to a V1 client with no BusinessProfiles.
DBAName
Moved to Client Details.DBAName.
FEIN
Moved to Client Details.FEINNum.
LicenseNumber
Moved to Client Details.LicenseNum.
NAICS
Moved to Client Details.NAICS
Name
Moved to Client Details.BusinessName
Contacts
Contacts that existed in V1 BusinessProfiles have been moved to the Client Contacts array.
BusinessProfile JSON
json
// v1
{
"businessProfiles": [
{
"dbaName": "",
"fein": "",
"licenseNumber": "",
"naics": "",
"name": "",
"type": "Corporation",
"contacts": [
{
"allowMarketing": false,
"contactType": "CellPhone",
"data": "",
"description": "",
"displayOrder": 1,
"isBillingContact": false
}
]
}
]
}
// v3
{
"details": {
"businessType": "Corporation",
"companyName": "", // from name
"dbaName": "",
"feinNum": "",
"licenseNum": "",
"naics": ""
},
"contacts": [
{
"type": "CellPhone",
"personId": null,
"allowMassEmail": false,
"isBillingContact": false,
"description": "",
"data": "",
"priority": 1
}
]
}// v1
{
"businessProfiles": [
{
"dbaName": "",
"fein": "",
"licenseNumber": "",
"naics": "",
"name": "",
"type": "Corporation",
"contacts": [
{
"allowMarketing": false,
"contactType": "CellPhone",
"data": "",
"description": "",
"displayOrder": 1,
"isBillingContact": false
}
]
}
]
}
// v3
{
"details": {
"businessType": "Corporation",
"companyName": "", // from name
"dbaName": "",
"feinNum": "",
"licenseNum": "",
"naics": ""
},
"contacts": [
{
"type": "CellPhone",
"personId": null,
"allowMassEmail": false,
"isBillingContact": false,
"description": "",
"data": "",
"priority": 1
}
]
}Claims
See Claim for details about changes to the Claim model.
Contacts
In the V1 API, this list only contained contacts that were not associated to a Person or Business. The list now contains all contacts for the client, with optional links to a Person. Client Contacts (those not associated with a Person) still appear in this list, along with Contact previously belonging to a BusinessProfile or Person. Clients linked to a person will have the PersonId property set.
See Contact for changes to the Contact model.
Details (new)
This is a new object, mostly containing properties that were moved from the Client object.
PersonalProfiles
Renamed to People. See Person for detailed changes.
Policies
The Policy list still contains all non-archived policies on the client. See Policy for details about changes to the Policy model.
Users
Removed. CSR and Producer are now located in Client Details.
Additional Interest
City
Removed. See Address.
Fax
No change.
IsArchived
Removed. Archived items are not included. This value was always false in the V1 API.
IsPayor
No change
LoanNumber
No change
Name
No change
Phone
No change
Rank
No change
State
Removed. See Address.
Type
TODO
ZipCode
Removed. See Address.
Address (new)
This object replaces the V1 City, State, and ZipCode properties. See Address for the full model.
Address
AddressType
Removed.
AtSince
Removed. See Details.PhysicalAtSince for Phsyical Address. This property is not stored for Mailing Address.
City
No change.
Country
Renamed to CountryCode.
Line1
Renamed to Address1
Line2
Renamed to Address2
State
No change.
ZipCode
Renamed to Zip
County
New in V3.
json
// v1
{
"addressType": "Mailing",
"atSince": null,
"city": "Seattle",
"country": "US",
"line1": "325 5th Ave N",
"line2": "#101",
"state": "WA",
"zipCode": "98109"
}
// v3
{
"address1": "325 5th Ave N", // from line1
"address2": "#101", // from line2
"city": "Seattle",
"state": "WA",
"zip": "98109", // from zipCode
"countryCode": "US", // from country
"county": "King" // new
}// v1
{
"addressType": "Mailing",
"atSince": null,
"city": "Seattle",
"country": "US",
"line1": "325 5th Ave N",
"line2": "#101",
"state": "WA",
"zipCode": "98109"
}
// v3
{
"address1": "325 5th Ave N", // from line1
"address2": "#101", // from line2
"city": "Seattle",
"state": "WA",
"zip": "98109", // from zipCode
"countryCode": "US", // from country
"county": "King" // new
}Animal Exposure
PersonalBuildingUnderwritingId
Removed. The Id can be inferred by the PersonalBuildingUnderwriting object in which the Anmial Exposure is listed.
AutoVehicle
The AutoVehicle replaces both PersonalAuto and CommercialAuto types from V1. The schema no longer depends on the value of the Type property. Optional PersonalInfo and CommercialInfo properties have been added to the AutoVehicle model.
Contact
AllowMarketing
Renamed to AllowMassEmail.
ContactType
No change.
Data
No change.
Description
No change.
DisplayOrder
Renamed to Priority. Contacts are no longer explicitly ordered. Some contacts may have the same priority value. A higher value means the contact is higher priority and should be used before other contacts with a lower value.
Coverage
ParentType (new)
All coverages are now listed at the Policy level. This property along with ParentId identifies the object a coverage belongs to.
Values: Policy, LOB, LocationReference, BuildingReference, Auto, Boat
ParentId (new)
All coverages are now listed at the Policy level. This property along with ParentType identifies the object a coverage belongs to.
Code
No change
Description
No change
DisplayOrder
Removed.
Limits
No change
Deductibles
No change
Premium
No change
Percent
No change
Options
Removed. Replaced by 3 sets of OptionCode and OptionDescription properties.
OptionCode1 (new)
OptionCode2 (new)
OptionCode3 (new)
OptionDescription1 (new)
OptionDescription2 (new)
OptionDescription3 (new)
AdditionalInterests
Removed. AdditionalInterests belonging to a coverage will be listed in the Policy level AdditionalInterests list with a ParentId referencing the Coverage.
LineOfBusiness
TODO
Location
TODO
Person
Contacts
Removed. Contacts linked to a Person will appear in the Client Contacts list.
EducationLevel
Renamed to Education.
Gender
See Gender (TODO)
Income
The type has changed from decimal to string (TODO?)
IsArchived
Removed. Archived Person records will no longer be returned.
IsMainContact
Moved to Client Details. The MainContacts list contains the Id of each Person who is a main contact.
MaritalStatus
TODO
NickName
Renamed to PreferredName.
Order
Removed.
ResidenceType
Renamed to Homeowner. TODO
YearOfBirth
Removed. DateOfBirth contains the year of birth.
Policy
AccountNumber
No change
AgentCode
No change
ApplicationType
TODO
BillingPlan
No change
Carrier
No longer optional.
CancellationDate
Removed. If status is Cancelled, then StatusDate is the scheduled Cancellation Date.
CurrentPremium
Removed
CurrentRate
Removed
DaysLapsed
Removed
EffectiveDate
No change
ExpirationDate
No change
InceptionDate
No change
IsArchived
Removed. Archived policies are not included and this value was always false.
NAIC
No change
OfficeId
No change
PaymentPlan
TODO
PolicyNumber
No change
Program
No longer optional.
QuotedPremium
This value is now optional.
Rater
Renamed to RaterCode
RenewalDate
Removed. If Status is Renewal, the StatusDate is the Renewal Date.
RewriteDate
Removed. If Status is Rewrute, the StatusDate is the Rewrite Date.
SoldDate
No change
Source
No change
State
Renamed to PolicyState
Type
No change
Status
The status values of "Suspect", "Quote", and "Expired" have been removed. The value "Unknown" has been renamed to "Unassigned". The remaining value are unchanged. See PolicyStatus for the full list of possible values.
StatusDate
No change.
SubStatus
No change
Term
TODO
Title
No longer optional
DisplayOrder
Renamed to PolicyIndex
TypeName
Removed. This value was previously used to determine which JSON model the policy adhered to (certain properties were only available on certain policy types). All policies now share the same model.
AdditionalInterests
See AdditionalInterest for details.
Coverages
This list now contains all coverages for the policy. Coverages that were previously found on Lines of Business, Autos, etc. are all contained in this list, and will have an appropriate ParentType and ParentId. See Coverage for details.
LineOfBusiness
See LineOfBusiness
Locations
See Location
LocationReferences (new)
This collection replaces the LineOfBusinessLocationBuildings list found on the V1 LineOfBusinessModel.
TODO: examples mapping Coverages on V1 LobLocation & LobLocationBuilding to Coverages pointing to a LocationReference or BuildingReference
Autos (new)
This list now contains all Personal and Commercial Auto Vehicles in a policy. In V1, Autos and Boats were found on the Vehicle list on each Line of Business. Autos and Boats have been separated and moved up to the Policy level. Each V3 Auto will have a LobId linking it to a Line of Business on the Policy.
Drivers (new)
This list now contains all Auto Drivers in a Policy. In V1, Auto Drivers and Boat Operators were found on the Drivers list on each Line of Business. Auto Drivers and Boat Operators have been separated and moved up to the Policy level. Each V3 Auto Driver will have a LobId linking it to a Line of Business on the Policy.
Boats (new)
This list contains all Boats in a Policy. In V1, Autos and Boats were found on the Vehicle list on each Line of Business. Autos and Boats have been separated and moved up to the Policy level. Each V3 Boat will have a LobId linking it to a Line of Business on the Policy.
BoatOperators (new)
This list now contains all Boat Operators in a Policy. In V1, Auto Drivers and Boat Operators were found on the Drivers list on each Line of Business. Auto Drivers and Boat Operators have been separated and moved up to the Policy level. Each V3 Boat Operator will have a LobId linking it to a Line of Business on the Policy.
Users
Removed. See Agent1, Agent2, and Agent3.
Log
Refid
No change
TS
No change
PolicyIndex
Renamed to PolicyId. Instead of identifying policies by their display order, they are now identified by their GUID Id.
Action
Renamed to Channel. The allowed values are unchnaged.
Description
Removed. See Note.
Body
Removed. See Note.
Note (new)
This field replaces the Description and Body fields from V1. To replicate the behavior of V1, include your Description as the first line of Note followed by the Body.
Suspense
Removed. See Task.
Task
Tasks replace V1 Suspenses and add new optional functionality. Users can be assigned by email instead of initials. Tasks also have a Title and Description field that can be used to provide more detail than a Suspense allowed.
Title (new)
Description (new)
Category
No change
DueDate
No change
AssignedToRole
No change
AssignedToEmail
Replaces V1 SuspendedForInitials