> ## Documentation Index > Fetch the complete documentation index at: https://docs.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # List Payees > Returns a paginated list of payees for the company. Payees are entities that receive payments, such as law firms, experts, vendors, etc. Filter by payee type, ID, or search text, and sort by various fields. Only returns saved payees (isSaved: true). **Required permission:** `company.payee:read` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/payees openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://app.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/external/companies/{companyId}/payees: get: tags: - Payees summary: List Payees description: > Returns a paginated list of payees for the company. Payees are entities that receive payments, such as law firms, experts, vendors, etc. Filter by payee type, ID, or search text, and sort by various fields. Only returns saved payees (isSaved: true). **Required permission:** `company.payee:read` operationId: listPayees parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/payeeIdFilter' - $ref: '#/components/parameters/payeeTypeFilter' - $ref: '#/components/parameters/filterText' - $ref: '#/components/parameters/payeeSortBy' - $ref: '#/components/parameters/sortDirection' - $ref: '#/components/parameters/page' responses: '200': description: Paginated list of payees content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Payee' totalCount: type: integer description: Total number of matching payees across all pages examples: success: summary: List of payees value: items: - id: 550e8400-e29b-41d4-a716-446655440001 companyId: 660e8400-e29b-41d4-a716-446655440000 name: Smith & Associates Law Firm payeeType: lawFirm email: contact@smithlaw.com alternateEmails: - billing@smithlaw.com 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 - id: 550e8400-e29b-41d4-a716-446655440002 companyId: 660e8400-e29b-41d4-a716-446655440000 name: Expert Forensics Inc payeeType: expert email: info@expertforensics.com alternateEmails: null phoneNumber: +1-555-987-6543 description: Forensic accounting experts address: null addressStructured: null lawFirmType: null bankInfo: null taxIdNumber: null externalPayee: null createdAt: '2025-01-10T08:00:00.000Z' createdBy: 880e8400-e29b-41d4-a716-446655440000 updatedAt: null updatedBy: null totalCount: 42 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier payeeIdFilter: name: id in: query schema: oneOf: - type: string format: uuid - type: array items: type: string format: uuid description: Filter by specific payee ID(s) payeeTypeFilter: name: payeeType in: query schema: $ref: '#/components/schemas/PayeeType' description: Filter by payee type filterText: name: filterText in: query schema: type: string description: Search across quote number, description, and other text fields payeeSortBy: name: sortBy in: query schema: type: string enum: - createdAt - updatedAt - name - email - payeeType default: createdAt description: Field to sort by (default createdAt) sortDirection: name: sortDirection in: query schema: type: string enum: - asc - desc default: desc description: Sort direction (default desc) page: name: page in: query schema: type: integer minimum: 1 default: 1 description: Page number (1-based, default 1, page size 50) schemas: Payee: type: object description: A payee entity (law firm, expert, vendor, etc.) properties: id: type: string format: uuid description: Payee identifier companyId: type: string format: uuid nullable: true description: Company identifier name: type: string description: Payee name payeeType: $ref: '#/components/schemas/PayeeType' email: type: string format: email nullable: true description: Primary email address alternateEmails: type: array items: type: string format: email nullable: true description: Additional email addresses phoneNumber: type: string nullable: true description: Phone number description: type: string nullable: true description: Description of the payee address: type: string nullable: true description: Unstructured address string addressStructured: allOf: - $ref: '#/components/schemas/PayeeAddressStructured' nullable: true description: Structured address with parsed components lawFirmType: allOf: - $ref: '#/components/schemas/LawFirmType' nullable: true description: Type of law firm (only for payeeType lawFirm) bankInfo: allOf: - $ref: '#/components/schemas/BankInfo' nullable: true description: Bank account information taxIdNumber: type: string nullable: true description: Tax identification number externalPayee: allOf: - $ref: '#/components/schemas/ExternalPayeeReference' nullable: true description: Reference to payee in external system createdAt: type: string format: date-time nullable: true description: When the payee was created (ISO 8601) createdBy: type: string format: uuid nullable: true description: User ID who created the payee updatedAt: type: string format: date-time nullable: true description: When the payee was last updated (ISO 8601) updatedBy: type: string format: uuid nullable: true description: User ID who last updated the payee PayeeType: type: string description: Type of payee enum: - lawFirm - expert - vendor - other - financingCompany PayeeAddressStructured: type: object description: Structured address with parsed components (payee-specific format) properties: city: type: string nullable: true description: City name country: type: string nullable: true description: Country name or code county: type: string nullable: true description: County name location: type: object nullable: true description: Geographic coordinates properties: lat: type: number description: Latitude lng: type: number description: Longitude name: type: string nullable: true description: Address name or label neighborhood: type: string nullable: true description: Neighborhood name postalCode: type: string nullable: true description: Postal/ZIP code state: type: object nullable: true description: State information properties: short: type: string description: State abbreviation (e.g., "CA") long: type: string description: Full state name (e.g., "California") streetName: type: string nullable: true description: Street name streetNumber: type: string nullable: true description: Street number sublocality: type: string nullable: true description: Sublocality or district timezone: type: string nullable: true description: Timezone identifier LawFirmType: type: string description: Type of law firm (only applicable when payeeType is lawFirm) enum: - defense - plaintiff BankInfo: type: object description: Bank account information for payments properties: bankAccountNumber: oneOf: - type: string - type: number description: Bank account number bankRoutingNumber: oneOf: - type: string - type: number description: Bank routing number ExternalPayeeReference: type: object description: Reference to an external payee in another system properties: payeeId: type: string description: External system payee ID payeeName: type: string description: External system payee name ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId message: type: string description: Description of the field error example: Required field is missing responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: UNAUTHORIZED message: Authorization header is required bearerTokenNotAllowed: summary: Bearer token used instead of API key value: error: code: UNAUTHORIZED message: External API endpoints require API key authentication Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: FORBIDDEN message: Insufficient permissions to perform this action InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: INTERNAL_ERROR message: An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Include your API key in the Authorization header. ````