Appearance
API V3.0
Versioning
To use the V3.0 API, include the following query parameter with every request: version=3.0
GET Agencies
This endpoint returns the agency ID for all agencies that have subscribed to a vendor’s application / service. Once an agency subscribes to and agrees to share data with a third-party application through the HawkSoft License Management Portal, their agency ID will be returned.
Request
bash
curl -v https://integration.hawksoft.app/vendor/agencies?version=3.0 -u [user]:[pwd] --basic
curl -v https://integration.hawksoft.app/vendor/agencies?version=3.0 -u [user]:[pwd] --basic
Response
txt
An array of one or more agencies subscribed to the vendor
[ 1, 2, 3 ]
An array of one or more agencies subscribed to the vendor
[ 1, 2, 3 ]
txt
No agencies are available to the vendor
No agencies are available to the vendor
txt
The provided credentials are invalid
The provided credentials are invalid
GET Agency Offices
This endpoint returns a list of offices defined for the agency ID.
Request
bash
curl -v https://integration.hawksoft.app/vendor/agency/1/offices?version=3.0 -u [user]:[pwd] --basic
curl -v https://integration.hawksoft.app/vendor/agency/1/offices?version=3.0 -u [user]:[pwd] --basic
Response
json
Returns an array of one or more Office objects
[
{
"OfficeId": 1,
"OfficeDescription": "",
"SubAgencyName": "",
"PrimaryOffice" true,
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"State": "",
"Zipcode": ""
}
]
Returns an array of one or more Office objects
[
{
"OfficeId": 1,
"OfficeDescription": "",
"SubAgencyName": "",
"PrimaryOffice" true,
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"State": "",
"Zipcode": ""
}
]
txt
The provided credentials are invalid
The provided credentials are invalid
txt
The requested agency is not available to the vendor
The requested agency is not available to the vendor
GET Changed Clients
Get a list of clients changed since a date. These Client IDs can be used when calling the Get Client or Get Client List endpoints.
Request
bash
curl -v https://integration.hawksoft.app/vendor/agency/[agencyId]/clients?version=3.0&asOf=[timestamp]&deleted=[deleted] -u [user]:[pwd] --basic
curl -v https://integration.hawksoft.app/vendor/agency/[agencyId]/clients?version=3.0&asOf=[timestamp]&deleted=[deleted] -u [user]:[pwd] --basic
URL Parameters
Name | Type | Optional | Description |
---|---|---|---|
AgencyId | Int | No |
Query Parameters
Name | Type | Optional | Description |
---|---|---|---|
AsOf | DateTime | Yes | |
OfficeId | Int | Yes | |
Deleted | Boolean | Yes |
Response
json
Returns an array of client IDs.
[ 1, 2, 3, 4 ]
Returns an array of client IDs.
[ 1, 2, 3, 4 ]
txt
The provided credentials are invalid
The provided credentials are invalid
txt
The requested agency is not available to the vendor
The requested agency is not available to the vendor
GET Client
Request
bash
curl -v https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]?version=3.0 -u [user]:[pwd] --basic
curl -v https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]?version=3.0 -u [user]:[pwd] --basic
Response
json
A Client object
{
"clientNumber": 1,
...
}
A Client object
{
"clientNumber": 1,
...
}
txt
The client does not exist.
The client does not exist.
See Client Model Reference for detailed documentation of the client model.
GET Client List
Request
bash
curl -v -x POST https://integration.hawksoft.app/vendor/agency/[agencyId]/clients?version=3.0 -u [user]:[pwd] --basic -d "{ 'clientNumbers': [1, 2]}"
curl -v -x POST https://integration.hawksoft.app/vendor/agency/[agencyId]/clients?version=3.0 -u [user]:[pwd] --basic -d "{ 'clientNumbers': [1, 2]}"
Response
json
An array of Client objects
[
{
"clientNumber": 1,
...
},
{
"clientNumber": 2,
...
}
]
An array of Client objects
[
{
"clientNumber": 1,
...
},
{
"clientNumber": 2,
...
}
]
See Client Model Reference for detailed documentation of the client model.
GET Client Search In Development HS6 Only
In Development
This feature is in development and subject to change.
Search an agency's clients. Currently the only supported search criteria is Policy Number.
Supports Client Includes
Request
URL
txt
https://integration.hawksoft.app/vendor/agency/[agencyId]/clients/search?version=3.0&policyNumber=POR83741&include=details,policies
https://integration.hawksoft.app/vendor/agency/[agencyId]/clients/search?version=3.0&policyNumber=POR83741&include=details,policies
URL Parameters
Name | Type | Optional | Description |
---|---|---|---|
AgencyId | Int | No |
Query Parameters
Name | Type | Optional | Description |
---|---|---|---|
PolicyNumber | String | No | Policy number to search for. Exact match only. |
Include | String | Yes | Comma delimited list of items to include in the response |
Response
json
An array of Client objects matching the search criteria.
An empty array is returned if no matching clients were found.
[
{
"clientNumber": 1,
...
},
{
"clientNumber": 2,
...
}
]
An array of Client objects matching the search criteria.
An empty array is returned if no matching clients were found.
[
{
"clientNumber": 1,
...
},
{
"clientNumber": 2,
...
}
]
json
Bad request. See response body for details.
Bad request. See response body for details.
See Client Model Reference for detailed documentation of the client model.
POST Log Note
Request
Body
Name | Type | Optional | Description |
---|---|---|---|
Channel | LogAction | No | |
Note | String | No | |
PolicyId | Guid | true | |
RefId | Guid | No | |
TS | DateTime | No | |
Task | Task | Yes |
Task
Name | Type | Optional | Description |
---|---|---|---|
AssignedToEmail | string | Yes | Required if AssignedToRole is "SpecifiedUser" |
AssignedToRole | Enum | No | "SpecifiedUser", "Producer", "CSR", "Agent1", "Agent2", or "Agent3" |
Category | String | Yes | |
Description | String | No | |
DueDate | DateTime | No | |
Title | String | No |
cURL Example
bash
curl -v -X POST https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/log?version=3.0 -u [user]:[pwd] --basic -d "{ 'refId': [guid], 'ts': '2024-08-19T22:42:51.069Z', 'policyIndex': 1, 'action': 1, 'description': 'Description', 'body': 'Log note' }"
curl -v -X POST https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/log?version=3.0 -u [user]:[pwd] --basic -d "{ 'refId': [guid], 'ts': '2024-08-19T22:42:51.069Z', 'policyIndex': 1, 'action': 1, 'description': 'Description', 'body': 'Log note' }"
Response
txt
The log was created successfully.
The log was created successfully.
txt
The request was saved and the log will be created next time the agency is connected to the cloud.
The request was saved and the log will be created next time the agency is connected to the cloud.
txt
Bad request. See response for details.
Bad request. See response for details.
txt
The provided credentials are invalid.
The provided credentials are invalid.
txt
The requested agency is not available, or the integration does not have permission to access this endpoint.
The requested agency is not available, or the integration does not have permission to access this endpoint.
POST Attachment
Request
Headers
Name | Type | Optional | Description |
---|---|---|---|
Channel | LogAction | No | |
Desc | String | No | Base64 encoded string. |
FileExt | String | No | |
FileName | String | No | |
LogNote | String | No | Base64 encoded string. |
PolicyId | Guid | Yes | |
RefId | Guid | No | |
TS | DateTime | No | |
TaskAssignedTo | AgentRole | No | |
TaskAssignedToEmail | string | No | |
TaskCategory | String | Yes | Base64 encoded string. |
TaskDescription | String | No | Base64 encoded string. |
TaskDueDate | DateTime | No | |
TaskTitle | String | No | Base64 encoded string. |
cURL Example
bash
curl -v -X POST https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/attachment?version=3.0 -u [user]:[pwd] --basic -H "RefId: [guid]" -H "TS: [timestamp]" -H "Desc: [string]" -H "LogNote: [string]" -H "FileName: [string]" -H "FileExt: [string]" -H "PolicyId: [guid]" -H "Channel: [int]" -d [data]
curl -v -X POST https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/attachment?version=3.0 -u [user]:[pwd] --basic -H "RefId: [guid]" -H "TS: [timestamp]" -H "Desc: [string]" -H "LogNote: [string]" -H "FileName: [string]" -H "FileExt: [string]" -H "PolicyId: [guid]" -H "Channel: [int]" -d [data]
Response
txt
The attachment was created successfully.
The attachment was created successfully.
txt
The request was saved and the attachment will be created next time the agency is connected to the cloud.
The request was saved and the attachment will be created next time the agency is connected to the cloud.
txt
Bad request. See response for details.
Bad request. See response for details.
txt
The provided credentials are invalid.
The provided credentials are invalid.
txt
The requested agency is not available, or the integration does not have permission to access this endpoint.
The requested agency is not available, or the integration does not have permission to access this endpoint.
POST Create Receipts In Development HS6 only
In Development - Limited Access to Select Partners
This section details functionality that is currently in development and only accessible to select partners assisting HawkSoft in testing. The functionality will not be available to you unless you are specifically invited by HawkSoft to test it.
Record a payment received by a client. A log note will be created and linked to the receipt. An optional task may be created and assigned to an agent for review.
Request
URL
txt
https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/receipts?version=3.0
https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/receipts?version=3.0
Body
A JSON array of one or more receipts.
Receipt
Name | Type | Optional | Description |
---|---|---|---|
Channel | LogAction | No | Describes the source of the interaction that generated the payment. |
Invoices | ReceiptInvoice[] | No | Designate one or more invoices to apply the payment to. |
LogNote | String | No | Text of the log note that will be associated with the payment |
OfficeId | Int | Yes | Optional office the payment should be associated with. If null, the office assigned to the client will be used. |
PolicyId | Guid | Yes | Optional policy the payment should be associated with. |
RefId | Guid | No | Unique Id for the reciept. |
TS | DateTime | No | The time the payment was received |
Task | Task | Yes | Optionally create a task assigned to an agency user |
ReceiptInvoice
Name | Type | Optional | Description |
---|---|---|---|
Amount | Decimal | No | The amount to apply to this invoice |
InvoiceId | Guid | No | Id of an invoice the payment will be applied to |
Task
Name | Type | Optional | Description |
---|---|---|---|
AssignedToEmail | string | Yes | Required if AssignedToRole is "SpecifiedUser" |
AssignedToRole | Enum | No | "SpecifiedUser", "Producer", "CSR", "Agent1", "Agent2", or "Agent3" |
Category | String | Yes | |
Description | String | No | |
DueDate | DateTime | No | |
Title | String | No |
Example
json
[
{
"refId": "aa6a4974-133e-4195-ac87-c6ff7f853a65",
"ts": "2024-08-19T22:42:51.069Z",
"policyId": null,
"officeId": null,
"channel": 29,
"logNote": "Online payment from insured",
"task": {
"title": "Review online payment",
"description": "Review payment on INV00000112",
"dueDate": "2024-08-19T22:42:51.069Z",
"assignedToRole": "CSR"
},
"total": 10.50,
"invoices": [
{
"invoiceId": "7fa2d453-7cea-4c87-8990-3934dc62b932",
"amount": 10.50
}
]
}
]
[
{
"refId": "aa6a4974-133e-4195-ac87-c6ff7f853a65",
"ts": "2024-08-19T22:42:51.069Z",
"policyId": null,
"officeId": null,
"channel": 29,
"logNote": "Online payment from insured",
"task": {
"title": "Review online payment",
"description": "Review payment on INV00000112",
"dueDate": "2024-08-19T22:42:51.069Z",
"assignedToRole": "CSR"
},
"total": 10.50,
"invoices": [
{
"invoiceId": "7fa2d453-7cea-4c87-8990-3934dc62b932",
"amount": 10.50
}
]
}
]
Response
json
Returns an array of responses for each item in the request.
[
{
"refId": "aa6a4974-133e-4195-ac87-c6ff7f853a65",
"code": 200,
"message": null
}
]
Returns an array of responses for each item in the request.
[
{
"refId": "aa6a4974-133e-4195-ac87-c6ff7f853a65",
"code": 200,
"message": null
}
]
txt
The credentials are invalid
The credentials are invalid
txt
The agency is not subscribed or has not granted access to this feature.
The agency is not subscribed or has not granted access to this feature.
Log Actions
Value | Description |
---|---|
1 | Phone To Insured |
2 | Phone To Carrier |
3 | Phone To Agency Staff |
4 | Phone To 3rd Party |
5 | Phone From Insured |
6 | Phone From Carrier |
7 | Phone From Agency Staff |
8 | Phone From 3rd Party |
9 | Mail To Insured |
10 | Mail To Carrier |
11 | Mail To Agency Staff |
12 | Mail To 3rd Party |
13 | Mail From Insured |
14 | Mail From Carrier |
15 | Mail From Agency Staff |
16 | Mail From 3rd Party |
17 | Walk In To Insured |
18 | Walk In To Carrier |
19 | Walk In To Agency Staff |
20 | Walk In To 3rd Party |
21 | Walk In From Insured |
22 | Walk In From Carrier |
23 | Walk In From Agency Staff |
24 | Walk In From 3rd Party |
25 | Online To Insured |
26 | Online To Carrier |
27 | Online To Agency Staff |
28 | Online To 3rd Party |
29 | Online From Insured |
30 | Online From Carrier |
31 | Online From Agency Staff |
32 | Online From 3rd Party |
33 | Email To Insured |
34 | Email To Carrier |
35 | Email To Agency Staff |
36 | Email To 3rd Party |
37 | Email From Insured |
38 | Email From Carrier |
39 | Email From Agency Staff |
40 | Email From 3rd Party |
41 | Text To Insured |
42 | Text To Carrier |
43 | Text To Agency Staff |
44 | Text To 3rd Party |
45 | Text From Insured |
46 | Text From Carrier |
47 | Text From Agency Staff |
48 | Text From 3rd Party |
49 | Chat To Insured |
50 | Chat To Carrier |
51 | Chat To Agency Staff |
52 | Chat To 3rd Party |
53 | Chat From Insured |
54 | Chat From Carrier |
55 | Chat From Agency Staff |
56 | Chat From 3rd Party |
Client Includes In Development
In Development
This feature is in development and may not work consistently for all agencies. For unsupported agencies, all available client data will be returned regardless of the include items specified.
All Client read endpoints support an optional include parameter, which allows you to limit the types of client data returned. The parameter is a comma delimited string containing one or more of the following: Details, People, Contacts, Claims, Polcies, Invoices. When this parameter is set, only the specified properties will be populated on the client response.
If this parameter is omitted, then the default data returned will include Details, People, Contacts, Claims, and Policies. This matches the original V3.0 behavior and does not require any action from partners who wish to continue receiving the same data as before.
Access to Invoices requires additional opt-in from each agency in the HawkSoft Marketplace. If you request data that an agency has not granted access to, then the request will succeed with only the data you have access to. If any requested data has been denied, the response will contain a header with the name "Denied" and a comma delimited list of the include items that were denied.