Skip to content
On this page

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

NameTypeOptionalDescription
AgencyIdIntNo

Query Parameters

NameTypeOptionalDescription
AsOfDateTimeYes
OfficeIdIntYes
DeletedBooleanYes

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.

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

NameTypeOptionalDescription
AgencyIdIntNo

Query Parameters

NameTypeOptionalDescription
PolicyNumberStringNoPolicy number to search for. Exact match only.
IncludeStringYesComma 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

NameTypeOptionalDescription
ChannelLogActionNo
NoteStringNo
PolicyIdGuidtrue
RefIdGuidNo
TSDateTimeNo
TaskTaskYes

Task

NameTypeOptionalDescription
AssignedToEmailstringYesRequired if AssignedToRole is "SpecifiedUser"
AssignedToRoleEnumNo"SpecifiedUser", "Producer", "CSR", "Agent1", "Agent2", or "Agent3"
CategoryStringYes
DescriptionStringNo
DueDateDateTimeNo
TitleStringNo

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-09-12T17:14:26.876Z', '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-09-12T17:14:26.876Z', '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

NameTypeOptionalDescription
ChannelLogActionNo
DescStringNoBase64 encoded string.
FileExtStringNo
FileNameStringNo
LogNoteStringNoBase64 encoded string.
PolicyIdGuidYes
RefIdGuidNo
TSDateTimeNo
TaskAssignedToAgentRoleNo
TaskAssignedToEmailstringNo
TaskCategoryStringYesBase64 encoded string.
TaskDescriptionStringNoBase64 encoded string.
TaskDueDateDateTimeNo
TaskTitleStringNoBase64 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

NameTypeOptionalDescription
ChannelLogActionNoDescribes the source of the interaction that generated the payment.
InvoicesReceiptInvoice[]NoDesignate one or more invoices to apply the payment to.
LogNoteStringNoText of the log note that will be associated with the payment
OfficeIdIntYesOptional office the payment should be associated with. If null, the office assigned to the client will be used.
PolicyIdGuidYesOptional policy the payment should be associated with.
RefIdGuidNoUnique Id for the reciept.
TSDateTimeNoThe time the payment was received
TaskTaskYesOptionally create a task assigned to an agency user

ReceiptInvoice

NameTypeOptionalDescription
AmountDecimalNoThe amount to apply to this invoice
InvoiceIdGuidNoId of an invoice the payment will be applied to

Task

NameTypeOptionalDescription
AssignedToEmailstringYesRequired if AssignedToRole is "SpecifiedUser"
AssignedToRoleEnumNo"SpecifiedUser", "Producer", "CSR", "Agent1", "Agent2", or "Agent3"
CategoryStringYes
DescriptionStringNo
DueDateDateTimeNo
TitleStringNo

Example

json
[
    {
        "refId": "aa6a4974-133e-4195-ac87-c6ff7f853a65",
        "ts": "2024-09-12T17:14:26.876Z",
        "policyId": null,
        "officeId": null,
        "channel": 29,
        "logNote": "Online payment from insured",
        "task": {
            "title": "Review online payment",
            "description": "Review payment on INV00000112",
            "dueDate": "2024-09-12T17:14:26.876Z",
            "assignedToRole": "CSR"
        },
        "total": 10.50,
        "invoices": [
            {
                "invoiceId": "7fa2d453-7cea-4c87-8990-3934dc62b932",
                "amount": 10.50
            }
        ]
    }
]
[
    {
        "refId": "aa6a4974-133e-4195-ac87-c6ff7f853a65",
        "ts": "2024-09-12T17:14:26.876Z",
        "policyId": null,
        "officeId": null,
        "channel": 29,
        "logNote": "Online payment from insured",
        "task": {
            "title": "Review online payment",
            "description": "Review payment on INV00000112",
            "dueDate": "2024-09-12T17:14:26.876Z",
            "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

ValueDescription
1Phone To Insured
2Phone To Carrier
3Phone To Agency Staff
4Phone To 3rd Party
5Phone From Insured
6Phone From Carrier
7Phone From Agency Staff
8Phone From 3rd Party
9Mail To Insured
10Mail To Carrier
11Mail To Agency Staff
12Mail To 3rd Party
13Mail From Insured
14Mail From Carrier
15Mail From Agency Staff
16Mail From 3rd Party
17Walk In To Insured
18Walk In To Carrier
19Walk In To Agency Staff
20Walk In To 3rd Party
21Walk In From Insured
22Walk In From Carrier
23Walk In From Agency Staff
24Walk In From 3rd Party
25Online To Insured
26Online To Carrier
27Online To Agency Staff
28Online To 3rd Party
29Online From Insured
30Online From Carrier
31Online From Agency Staff
32Online From 3rd Party
33Email To Insured
34Email To Carrier
35Email To Agency Staff
36Email To 3rd Party
37Email From Insured
38Email From Carrier
39Email From Agency Staff
40Email From 3rd Party
41Text To Insured
42Text To Carrier
43Text To Agency Staff
44Text To 3rd Party
45Text From Insured
46Text From Carrier
47Text From Agency Staff
48Text From 3rd Party
49Chat To Insured
50Chat To Carrier
51Chat To Agency Staff
52Chat To 3rd Party
53Chat From Insured
54Chat From Carrier
55Chat From Agency Staff
56Chat 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.