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

200204401

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

200401403

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
AsOf	DateTime	Yes
OfficeId	Int	Yes
Deleted	Boolean	Yes

Response

200401403

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

200404

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

200

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

200400

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
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-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

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-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

200401403

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.

API V3.0 ​

Versioning ​

GET Agencies ​

Request ​

Response ​

GET Agency Offices ​

Request ​

Response ​

GET Changed Clients ​

Request ​

URL Parameters ​

Query Parameters ​

Response ​

GET Client ​

Request ​

Response ​

GET Client List ​

Request ​

Response ​

GET Client Search In Development HS6 Only ​

Request ​

URL ​

URL Parameters ​

Query Parameters ​

Response ​

POST Log Note ​

Request ​

Body ​

Task ​

cURL Example ​

Response ​

POST Attachment ​

Request ​

Headers ​

cURL Example ​

Response ​

POST Create Receipts In Development HS6 only ​

Request ​

URL ​

Body ​

Receipt ​

ReceiptInvoice ​

Task ​

Example ​

Response ​

Log Actions ​

Client Includes In Development ​

API V3.0

Versioning

GET Agencies

Request

Response

GET Agency Offices

Request

Response

GET Changed Clients

Request

URL Parameters

Query Parameters

Response

GET Client

Request

Response

GET Client List

Request

Response

GET Client Search In Development HS6 Only

Request

URL

URL Parameters

Query Parameters

Response

POST Log Note

Request

Body

Task

cURL Example

Response

POST Attachment

Request

Headers

cURL Example

Response

POST Create Receipts In Development HS6 only

Request

URL

Body

Receipt

ReceiptInvoice

Task

Example

Response

Log Actions

Client Includes In Development