Overview

Payees are entities that receive payments, such as law firms, experts, vendors, and other third parties. The Payees API allows you to programmatically create, read, update, and delete payee information within your company.

Key Concepts:

• Payees represent external entities that receive payments from insurance operations
• Each payee has a type (lawFirm, expert, vendor, other, financingCompany)
• Law firm payees can specify a law firm type (defense or plaintiff)
• Payees can have bank information for payment processing
• Only “saved” payees (isSaved: true) are returned by the API. A non-saved payee is one that was created via a UI flow but for which no transaction was ever completed.

---

API Endpoints

• List Payees - Retrieve paginated list of payees with filtering and sorting
• Get Payee - Retrieve a single payee by ID
• Create Payee - Create a new payee
• Update Payee - Update an existing payee
• Delete Payee - Soft delete a payee

---

Payee Types

Type	Description
lawFirm	Law firm (can specify defense or plaintiff)
expert	Expert witness or consultant
vendor	Third-party vendor or service provider
other	Other type of payee
financingCompany	Financing or premium finance company

---

Law Firm Types

When payeeType is lawFirm, you can specify the lawFirmType:

Type	Description
defense	Defense counsel representing the insured
plaintiff	Plaintiff counsel (opposing party)

---

Structured Address

The addressStructured field contains a detailed address object with the following fields:

Field	Type	Description
streetNumber	string	Street number
streetName	string	Street name
city	string	City name
state	object	State with short and long properties
postalCode	string	ZIP or postal code
country	string	Country name or code
county	string	County name
neighborhood	string	Neighborhood name
sublocality	string	Sublocality or district
timezone	string	Timezone identifier
location	object	Geographic coordinates (lat, lng)

---

Bank Information

The bankInfo field contains payment information:

Field	Type	Description
bankAccountNumber	string or number	Bank account number
bankRoutingNumber	string or number	Bank routing number

---

Nullable Fields

The following fields may be null in the response:

Field	When null
email	Email not provided
alternateEmails	No alternate emails provided
phoneNumber	Phone number not provided
description	Description not provided
address	Unstructured address not provided
addressStructured	Structured address not provided
lawFirmType	Payee is not a law firm
bankInfo	Bank information not provided
taxIdNumber	Tax ID not provided
externalPayee	No external system reference
createdAt	Timestamp not tracked (legacy records)
createdBy	Created by system or unknown user
updatedAt	Payee has never been updated
updatedBy	Never updated or updated by system

---

Filtering and Sorting

List endpoints support comprehensive filtering and sorting options:

Filter Parameters

Parameter	Type	Description
id	string or array	Filter by specific payee ID(s)
payeeType	string	Filter by payee type
filterText	string	Text search across payee name

Sorting Parameters

Parameter	Type	Default	Description
sortBy	string	createdAt	Field to sort by (createdAt, updatedAt, name, email, payeeType)
sortDirection	string	desc	Sort direction (asc or desc)

Pagination

Parameter	Type	Default	Description
page	integer	1	Page number (1-based, page size 50)

Response includes:

• items - Array of payees for the current page
• totalCount - Total number of matching payees across all pages

---

Permissions

Access to payees requires the appropriate permissions based on your API key:

Operation	Required Permission
List Payees	company.payee:read
Get Payee	company.payee:read
Create Payee	company.payee:create
Update Payee	company.payee:create
Delete Payee	company.payee:create

---

Example Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "companyId": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Smith & Associates Law Firm",
      "payeeType": "lawFirm",
      "email": "[e-mail]",
      "alternateEmails": ["[e-mail]"],
      "phoneNumber": "[phone]",
      "description": "Defense law firm specializing in insurance litigation",
      "address": "123 Legal Plaza, Suite 500, New York, NY 10001",
      "addressStructured": {
        "streetNumber": "123",
        "streetName": "Legal Plaza",
        "city": "New York",
        "state": {
          "short": "NY",
          "long": "New York"
        },
        "postalCode": "10001",
        "country": "US"
      },
      "lawFirmType": "defense",
      "bankInfo": {
        "bankAccountNumber": "****1234",
        "bankRoutingNumber": "****5678"
      },
      "taxIdNumber": "12-3456789",
      "externalPayee": null,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "createdBy": "880e8400-e29b-41d4-a716-446655440000",
      "updatedAt": "2025-01-16T14:20:00.000Z",
      "updatedBy": "880e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "totalCount": 42
}

---