Read client records for an agency. Fetch a single client by id, batch up to a list of clients, list clients changed since a timestamp for incremental sync, and search clients. In V3.0 a client payload consolidates contacts, policies and coverages, vehicles, and drivers under HawkSoft 6's cloud data model. Endpoint paths are from public Partner API docs; access is gated behind partner credentials and agency opt-in.
openapi: 3.0.3
info:
title: HawkSoft Partner API
version: '3.0'
description: >-
HawkSoft Partner API for insurance agency management. This OpenAPI document
describes the documented Partner API surface (V3.0, with reference to V1.8).
IMPORTANT - endpoint modeling honesty: The paths, HTTP methods, and base URL
below are taken from HawkSoft's publicly readable Partner API documentation
at https://partner.hawksoft.app. The Partner API is GATED - credentials are
issued only to vetted, approved API Partners, and an agency must opt in to
share its data, so the request/response schemas here are MODELED from the
published documentation and blog descriptions rather than exercised against
a live account. Field-level detail should be confirmed against the official
docs and a partner sandbox before implementation.
Authentication is HTTP Basic (partner user and password). All V3.0 requests
must include the query parameter version=3.0.
contact:
name: HawkSoft Partner Program
email: opportunities@hawksoft.com
url: https://partner.hawksoft.app/
termsOfService: https://www.hawksoft.com/terms/api/
servers:
- url: https://integration.hawksoft.app
description: HawkSoft Partner API integration host
security:
- basicAuth: []
tags:
- name: Agencies
description: Agencies and their offices
- name: Clients
description: Client records including contacts, policies, coverages, vehicles, and drivers
- name: Log Entries
description: Write-back activity log notes
- name: Attachments
description: File attachments on client records
- name: Receipts
description: Payment receipts on client records
paths:
/vendor/agencies:
get:
operationId: listAgencies
summary: List authorized agencies
description: >-
Return the agencies that have authorized this partner. Use the returned
agencyId in all subsequent requests.
tags:
- Agencies
parameters:
- $ref: '#/components/parameters/Version'
responses:
'200':
description: A list of agencies
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Agency'
'401':
$ref: '#/components/responses/Unauthorized'
/vendor/agency/{agencyId}/offices:
get:
operationId: listOffices
summary: List an agency's offices
tags:
- Agencies
parameters:
- $ref: '#/components/parameters/AgencyId'
- $ref: '#/components/parameters/Version'
responses:
'200':
description: A list of offices for the agency
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Office'
'401':
$ref: '#/components/responses/Unauthorized'
/vendor/agency/{agencyId}/clients:
get:
operationId: listChangedClients
summary: List clients changed since a timestamp
description: >-
Return client identifiers (and change metadata) for clients modified
since the supplied timestamp, enabling incremental synchronization.
tags:
- Clients
parameters:
- $ref: '#/components/parameters/AgencyId'
- $ref: '#/components/parameters/Version'
- name: since
in: query
description: Return clients modified at or after this ISO 8601 timestamp.
required: false
schema:
type: string
format: date-time
responses:
'200':
description: Changed client references
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ClientReference'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: getClientList
summary: Fetch a batch of clients by id
description: >-
Return full client records for the supplied list of client ids. The
documented batch limit is up to 200 client ids per request.
tags:
- Clients
parameters:
- $ref: '#/components/parameters/AgencyId'
- $ref: '#/components/parameters/Version'
requestBody:
required: true
content:
application/json:
schema:
type: array
maxItems: 200
items:
type: string
description: Client id
responses:
'200':
description: Full client records
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Client'
'401':
$ref: '#/components/responses/Unauthorized'
/vendor/agency/{agencyId}/clients/search:
get:
operationId: searchClients
summary: Search clients
tags:
- Clients
parameters:
- $ref: '#/components/parameters/AgencyId'
- $ref: '#/components/parameters/Version'
- name: q
in: query
description: Search term (name, phone, email, or policy attributes).
required: false
schema:
type: string
responses:
'200':
description: Matching clients
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Client'
'401':
$ref: '#/components/responses/Unauthorized'
/vendor/agency/{agencyId}/client/{clientId}:
get:
operationId: getClient
summary: Get a single client
description: >-
Return a full client record. In V3.0 the payload consolidates contacts,
policies and coverages, vehicles, and drivers under the HawkSoft 6 cloud
data model.
tags:
- Clients
parameters:
- $ref: '#/components/parameters/AgencyId'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/Version'
responses:
'200':
description: A client record
content:
application/json:
schema:
$ref: '#/components/schemas/Client'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Client not found
/vendor/agency/{agencyId}/client/{clientId}/log:
post:
operationId: postLogNote
summary: Post a log note to a client (write-back)
description: >-
Append an activity log note to a client's timeline. Core of HawkSoft's
2-way integration; available to partners using write-back.
tags:
- Log Entries
parameters:
- $ref: '#/components/parameters/AgencyId'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/Version'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LogNote'
responses:
'201':
description: Log note created
'401':
$ref: '#/components/responses/Unauthorized'
/vendor/agency/{agencyId}/client/{clientId}/attachment:
post:
operationId: postAttachment
summary: Post a file attachment to a client (write-back)
tags:
- Attachments
parameters:
- $ref: '#/components/parameters/AgencyId'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/Version'
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Attachment'
responses:
'201':
description: Attachment created
'401':
$ref: '#/components/responses/Unauthorized'
/vendor/agency/{agencyId}/client/{clientId}/receipts:
post:
operationId: postReceipt
summary: Post a payment receipt to a client (write-back, V3.0)
tags:
- Receipts
parameters:
- $ref: '#/components/parameters/AgencyId'
- $ref: '#/components/parameters/ClientId'
- $ref: '#/components/parameters/Version'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Receipt'
responses:
'201':
description: Receipt created
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic authentication with partner-issued credentials.
parameters:
Version:
name: version
in: query
required: true
description: API version; use 3.0 for the V3.0 surface.
schema:
type: string
default: '3.0'
AgencyId:
name: agencyId
in: path
required: true
description: HawkSoft agency identifier.
schema:
type: string
ClientId:
name: clientId
in: path
required: true
description: HawkSoft client identifier.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid partner credentials.
schemas:
Agency:
type: object
properties:
agencyId:
type: string
name:
type: string
status:
type: string
Office:
type: object
properties:
officeId:
type: string
name:
type: string
address:
type: string
phone:
type: string
ClientReference:
type: object
properties:
clientId:
type: string
modified:
type: string
format: date-time
Client:
type: object
description: >-
Consolidated V3.0 client record. Modeled from public documentation;
confirm exact fields against the official Partner API docs.
properties:
clientId:
type: string
modified:
type: string
format: date-time
contacts:
type: array
items:
$ref: '#/components/schemas/Contact'
policies:
type: array
items:
$ref: '#/components/schemas/Policy'
vehicles:
type: array
items:
type: object
drivers:
type: array
items:
type: object
Contact:
type: object
properties:
contactId:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
phone:
type: string
priority:
type: integer
Policy:
type: object
properties:
policyId:
type: string
policyNumber:
type: string
lineOfBusiness:
type: string
carrier:
type: string
status:
type: string
effectiveDate:
type: string
format: date
expirationDate:
type: string
format: date
coverages:
type: array
items:
type: object
LogNote:
type: object
required:
- description
properties:
action:
type: string
description:
type: string
timestamp:
type: string
format: date-time
Attachment:
type: object
properties:
fileName:
type: string
contentType:
type: string
file:
type: string
format: binary
Receipt:
type: object
properties:
amount:
type: number
method:
type: string
reference:
type: string
timestamp:
type: string
format: date-time