Skip to main content
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

​
Payee Types

TypeDescription
lawFirmLaw firm (can specify defense or plaintiff)
expertExpert witness or consultant
vendorThird-party vendor or service provider
otherOther type of payee
financingCompanyFinancing or premium finance company

​
Law Firm Types

When payeeType is lawFirm, you can specify the lawFirmType:
TypeDescription
defenseDefense counsel representing the insured
plaintiffPlaintiff counsel (opposing party)

​
Structured Address

The addressStructured field contains a detailed address object with the following fields:
FieldTypeDescription
streetNumberstringStreet number
streetNamestringStreet name
citystringCity name
stateobjectState with short and long properties
postalCodestringZIP or postal code
countrystringCountry name or code
countystringCounty name
neighborhoodstringNeighborhood name
sublocalitystringSublocality or district
timezonestringTimezone identifier
locationobjectGeographic coordinates (lat, lng)

​
Bank Information

The bankInfo field contains payment information:
FieldTypeDescription
bankAccountNumberstring or numberBank account number
bankRoutingNumberstring or numberBank routing number

​
Nullable Fields

The following fields may be null in the response:
FieldWhen null
emailEmail not provided
alternateEmailsNo alternate emails provided
phoneNumberPhone number not provided
descriptionDescription not provided
addressUnstructured address not provided
addressStructuredStructured address not provided
lawFirmTypePayee is not a law firm
bankInfoBank information not provided
taxIdNumberTax ID not provided
externalPayeeNo external system reference
createdAtTimestamp not tracked (legacy records)
createdByCreated by system or unknown user
updatedAtPayee has never been updated
updatedByNever updated or updated by system

​
Filtering and Sorting

List endpoints support comprehensive filtering and sorting options:

​
Filter Parameters

ParameterTypeDescription
idstring or arrayFilter by specific payee ID(s)
payeeTypestringFilter by payee type
filterTextstringText search across payee name

​
Sorting Parameters

ParameterTypeDefaultDescription
sortBystringcreatedAtField to sort by (createdAt, updatedAt, name, email, payeeType)
sortDirectionstringdescSort direction (asc or desc)

​
Pagination

ParameterTypeDefaultDescription
pageinteger1Page 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:
OperationRequired Permission
List Payeescompany.payee:read
Get Payeecompany.payee:read
Create Payeecompany.payee:create
Update Payeecompany.payee:create
Delete Payeecompany.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": "[email protected]",
      "alternateEmails": ["[email protected]"],
      "phoneNumber": "+1-555-123-4567",
      "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
}