HawkSoft Partner API

Appearance

On this page

API Overview ​

Authentication ​

The HawkSoft API supports basic authentication. Your Client Id is your username and your Client Secret is your password.

bash
curl -v https://integration.hawksoft.app/vendor/agencies -u [user]:[pwd] --basic
curl -v https://integration.hawksoft.app/vendor/agencies -u [user]:[pwd] --basic

Troubleshooting Authentication Errors ​

401 ​

A 401 response code means that the required authorization header is missing or invalid. Ensure your credentials are correct and that the Authorization header is valid.

You can verify your credentials in the command line by replacing [user] with your Client Id and [pwd] with your Client Secret in the above request and running it in the command line.

If you are manually building an authorization header, make sure it is formatted correctly. The header must be of the form Authorization: Basic [credentials], where [credentials] is the base64 encoding of your Client Id and Client Secret joined by a ':'. For an integration with Client Id "abc" and Client Secret "123", the authorization header will be: Authorization: Basic YWJjOjEyMw==

403 ​

A 403 response code means that your credentials are valid, but you are trying to access an Agency that is not available to your integration. The agency may have opted out of data sharing through the HawkSoft Marketplace, or they may no longer be an active HawkSoft customer.

Sandbox Testing ​

As part of onboarding, partners will be provided with a sandbox HawkSoft installation and access to a staging environment API for testing.

Sync Agency Data ​

The basic sync workflow is this:

  1. Get a list of agencies you have access to.
  2. (Optional) For each agency, read the list of agency offices.
  3. For each agency, find out which clients have changed since your last sync.
  4. Read each changed client for each agency.

Keep reading for a detailed explanation of each step.

Choose a Sync Interval ​

Decide on a sync interval that fits the needs of your integration. Partners generally choose to sync on intervals between 1 and 24 hours.

Get Agencies ​

This endpoint returns a list of agencies that have opted in to sharing data with your integration. These are the agencyIds you will provide to the Get Agency Offices, Get Changed Clients, and Get Client endpoints.

See: Get Agencies

Get Agency Offices ​

For each agency, this endpoint returns a list of office names and addresses.

See: Get Agency Offices

Get Changed Clients ​

The first time you sync a new agency, call this endpoint without the asOf parameter. This will return a list of all client Ids for the agency. You will provide these client Ids to the Get Clients endpoint when reading client data. Durning subsequent syncs for an agency, set the asOf parameter to the time of your last sync. Only a percentage of clients change on a given day, and using this endpoint reduces the time and resources required to sync an agency.

See: Get Changed Clients

Get Clients ​

This endpoint allows you to read clients in batches of up to 200. Use this endpoint to read each client returned in the Get Changed Clients response.

See: Get Clients