API V4.0

To use the V4.0 API, include the following query parameter with every request: version=4.0

Client Includes

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.

Example:

GET https://integration.hawksoft.app/vendor/agencies/client/1?version=4.0&include=People,Policies

GET Agencies

This endpoint returns the all agencies that have subscribed to a partner'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, along with the scopes that each agency has opted to enable.

Request

curl -v https://integration.hawksoft.app/vendor/agencies?version=4.0 -u [user]:[pwd] --basic

Response

200

An array of one or more agencies subscribed to the vendor

[
    {
        "agencyId": 1,
        "scopes": [ "client-read" ]
    },
    {
        "agencyId": 2,
        "scopes": [ "client-read", "create-log-attachment-task" ]
    },
    {
        "agencyId": 3,
        "scopes": [ "client-read", "create-log-attachment-task", "client-create" ]
    }
]

204

No agencies are available to the vendor

401

The provided credentials are invalid

GET Agency Offices

This endpoint returns a list of offices defined for the agency ID.

Request

curl -v https://integration.hawksoft.app/vendor/agency/1/offices?version=4.0 -u [user]:[pwd] --basic

Response

200

Returns an array of one or more Office objects

[
	{
		"OfficeId": 1,
		"OfficeDescription": "",
		"SubAgencyName": "",
		"PrimaryOffice" true,
		"AddressLine1": "",
		"AddressLine2": "",
		"City": "",
		"State": "",
		"Zipcode": ""
	}
]

401

The provided credentials are invalid

403

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

curl -v https://integration.hawksoft.app/vendor/agency/[agencyId]/clients?version=4.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

200

Returns an array of client IDs.
[ 1, 2, 3, 4 ]

401

The provided credentials are invalid

403

The requested agency is not available to the vendor

GET Client

Request

curl -v https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]?version=4.0 -u [user]:[pwd] --basic

Response

200

A Client object

{
    "clientNumber": 1,
    ...
}

404

The client does not exist.

See Client Model Reference for detailed documentation of the client model.

GET Client List

Request

curl -v -x POST https://integration.hawksoft.app/vendor/agency/[agencyId]/clients?version=4.0 -u [user]:[pwd] --basic -d "{ 'clientNumbers': [1, 2]}"

Response

200

An array of Client objects

[
    {
        "clientNumber": 1,
        ...
    },
    {
        "clientNumber": 2,
        ...
    }
]

See Client Model Reference for detailed documentation of the client model.

GET Client Search

Search an agency's clients. Currently the only supported search criteria is Policy Number.

Supports Client Includes

Request

https://integration.hawksoft.app/vendor/agency/[agencyId]/clients/search?version=4.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

200

An array of Client objects matching the search criteria.

An empty array is returned if no matching clients were found.

[
    {
        "clientNumber": 1,
        ...
    },
    {
        "clientNumber": 2,
        ...
    }
]

400

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

curl -v -X POST https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/log?version=4.0 -u [user]:[pwd] --basic -d "{ 'refId': [guid], 'ts': '2026-07-05T17:32:04.232Z', 'policyIndex': 1, 'action': 1, 'description': 'Description', 'body': 'Log note' }"

Response

200

The log was created successfully.

202

The request was saved and the log will be created next time the agency is connected to the cloud.

400

Bad request. See response for details.

401

The provided credentials are invalid.

403

The requested agency is not available, or the integration does not have permission to access this endpoint.

POST Attachment

Attach a file to a client. Supported file types include: pdf, jpg/jpeg, mp3, and png. The maximum file size accepted is 5 Mb.

Request

Headers

Name	Type	Optional	Description
Channel	LogAction	No
Desc	String	No	Base64 encoded string.
FileExt	String	No
FileName	String	No	Base64 encoded string. The name of the file, excluding the file extension.
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

curl -v -X POST https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/attachment?version=4.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

200

The attachment was created successfully.

202

The request was saved and the attachment will be created next time the agency is connected to the cloud.

400

Bad request. See response for details.

401

The provided credentials are invalid.

403

The requested agency is not available, or the integration does not have permission to access this endpoint.

POST Create Receipts

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

https://integration.hawksoft.app/vendor/agency/[agencyId]/client/[clientId]/receipts?version=4.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[]	Yes	Optionally 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.
PayMethod	PayMethod	Yes	Optionally specify the customer's payment method. If not set, defaults to 'Other'.
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

[
    {
        "refId": "aa6a4974-133e-4195-ac87-c6ff7f853a65",
        "ts": "2026-07-05T17:32:04.232Z",
        "policyId": null,
        "officeId": null,
        "channel": 29,
        "logNote": "Online payment from insured",
        "task": {
            "title": "Review online payment",
            "description": "Review payment on INV00000112",
            "dueDate": "2026-07-05T17:32:04.232Z",
            "assignedToRole": "CSR"
        },
        "total": 10.50,
        "invoices": [
            {
                "invoiceId": "7fa2d453-7cea-4c87-8990-3934dc62b932",
                "amount": 10.50
            }
        ]
    }
]

Response

200

Returns an array of responses for each item in the request.
[
    {
        "refId": "aa6a4974-133e-4195-ac87-c6ff7f853a65",
        "code": 200,
        "message": null
    }
]

401

The credentials are invalid

403

The agency is not subscribed or has not granted access to this feature.

POST Create Client

Create a new client in the specified agency.

This endpoint has a rate limit of 25 requests per second. Requests exceeding this limit will be rejected with a 429 status code.

If BusinessDetail is included, then the client will be marked as a Commercial Customer Type, and IsCommercial will be set to true when reading the created client. Otherwise, the client will be marked as a Personal Customer Type, and IsPersonal will be set to true.

Request

curl -v -X POST {{ theme.apiUrl }}/vendor/agency/[agencyId]/client?version=4.0 -u [user]:[pwd] --basic -d "{ ... }"

Name	Type	Optional	Description
AgencyId	Int	No	The agency in which to create the client.

Body

A JSON ClientCreateRequest object.

ClientCreateRequest

Name	Type	Optional	Description
BusinessDetail	ClientBusinessDetail	Yes	Optional business details for commercial clients.
Contacts	ContactCreateRequest[]	Yes	Optional client-level contact information. Maximum of 5 items.
Log	LogCreateRequest	No	Log note to create with the client.
MailingAddress	AddressCreateRequest	Yes	Optional mailing address for the client.
OfficeId	Int16	Yes	Office to assign the client to. Defaults to the agency default office if not set.
People	PersonCreateRequest[]	No	Up to 11 people to associate with the client. Exactly one person with MainContactType=First is required. No more than one person with MainContactType=Second is allowed.
Policy	PolicyCreateRequest	Yes	Optional policy shell to create with the client.
Source	String	Yes	Max length of 14.
Status	ClientStatus	Yes	Initial client status. Defaults to Prospect if not set.
Task	TaskCreateRequest	Yes	Optional task to create and assign to an agency user. If using Csr, Producer, or Agent1/2/3 roles, and the agency does not have a default user configured for your chosen role, then the request will fail.

ClientBusinessDetail

Name	Type	Optional	Description
BusinessType	BusinessType	No	Type of business entity.
CompanyName	String	No	Legal company name. Maximum length: 60.
DBAName	String	Yes	Doing-business-as name. Maximum length: 60.
FeinNum	String	Yes	Federal Employer Identification Number. Maximum length: 9. All characters must be digits (0-9)
LicenseNum	String	Yes	Business license number. Maximum length: 30.
NAICS	String	Yes	North American Industry Classification System code. Maximum length: 6.
Website	String	Yes	Company website URL. Maximum length: 128.

AddressCreateRequest

Name	Type	Optional	Description
Address1	String	Yes	First line of the street address. Maximum length: 40.
Address2	String	Yes	Second line of the street address. Maximum length: 40.
City	String	Yes	City name. Maximum length: 19.
State	String	Yes	State or province abbreviation. Must be 2 characters if set.
Zip	String	Yes	Postal or ZIP code. Maximum length: 10.

PersonCreateRequest

Name	Type	Optional	Description
Contacts	ContactCreateRequest[]	Yes	Contact information for this person. Maximum of 5 items.
DateOfBirth	DateOnly	Yes	Date of birth.
DriverLicenseNumber	String	Yes	Driver license number. Maximum length: 25.
FirstName	String	Yes	Person's first name. Maximum length: 14.
LastName	String	Yes	Person's last name. Maximum length: 24.
MainContactType	MainContactType	No	Which named insured slot this person occupies, if any.

ContactCreateRequest

Name	Type	Optional	Description
Type	ContactType	No	Type of contact, such as phone or email.
Value	String	No	Contact value, such as a phone number or email address. Maximum length: 128.

PolicyCreateRequest

Name	Type	Optional	Description
ApplicationType	ApplicationType	Yes	Application type for the policy.
EffectiveDate	DateOnly	Yes	Policy effective date. Must be on or after 1970-01-01.
LOBs	String[]	Yes	Lines of business to include on the policy. Maximum of 12 items.
PolicyNumber	String	Yes	Policy number. Maximum length: 25.
State	String	Yes	Policy state abbreviation. Must be 2 characters if set.

LogCreateRequest

Name	Type	Optional	Description
Channel	Int32	No	Channel describing the source of the interaction.
Note	String	No	Text of the log note. Maximum length: 3,000.
PolicyId	Guid	Yes	Optional policy to associate with the log entry.
TS	DateTime	No	Timestamp of the log entry.

TaskCreateRequestV2

Name	Type	Optional	Description
AssignedToEmail	String	Yes	Email of the user to assign the task to. Required when AssignedToRole is SpecifiedUser.
AssignedToRole	AgentRole	No	Agency role to assign the task to.
Category	String	Yes	Task category. Maximum length: 50.
Description	String	No	Task description. Maximum length: 4,000.
DueDate	DateTime	No	Date the task is due.
Title	String	No	Task title. Maximum length: 50.

Response

200

Success. Returns the ClientNumber of the new client, 
which can be used to read the client using the GET Client 
or POST Client List endpoints.

{
    "clientNumber": 123    
}

400

The request is invalid. See the response body for detailed 
validation error messages.

403

The agency is either not subscribed, or has not opted into 
the Client Create scope. See the GET Agencies endpoint 
to determine which agencies are subscribed and which features 
each agency has enabled.

429

You have exceeded the rate limit of 25 requests per second.
Wait 1 second before retrying.

Enumerations

AgentRole

Value	Description
SpecifiedUser
Producer
CSR
Agent1
Agent2
Agent3

ApplicationType

Value	Description
Undefined
Agricultural
Commercial
EmployeeBenefits
Health
Life
Other
Personal
SuretyBond
HawkSoft

BusinessType

Value	Description
None
Corporation
IndividualOrSoleProprietor
SubchapterS
LLC
Partnership
JointVenture
NonProfit
FamilyTrust

ClientStatus

Value	Description
Active
DeadFile
Prospect
Lead

ContactType

Value	Description
None
WorkPhone
WorkEmail
CellPhone
HomePhone
HomeEmail
OtherPhone
OtherEmail
MessagePhone
Pager
Fax
SocialMedia
ClientWebsite
OtherWebsite

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

MainContactType

Value	Description
None
First
Second
Other