> ## Documentation Index > Fetch the complete documentation index at: https://docs.getenso.ai/llms.txt > Use this file to discover all available pages before exploring further. # API to get entities by type with filters > Get a paginated list of customer entities with selectable attributes, filtering, grouping, and sorting. **SystemUser permission:** `EntityService:getEntitiesByTypeWithFilters, JobService:create` ## OpenAPI ````yaml get /entities/list openapi: 3.0.3 info: title: Enso API description: >- REST API for Enso's billing & metering platform. This reference covers endpoints accessible to the SystemUser role — the role used by API integrations. version: 1.0.0 license: name: Proprietary servers: - url: https://api.getenso.ai description: Production security: - bearerAuth: [] tags: - name: Apps description: Third-party app integrations and credentials - name: Attributes description: Custom attribute definitions on catalog/customer entities - name: Auth description: Exchange API credentials for an access token - name: Billing description: Plans and plan items — what your contracts apply - name: Catalog description: SKUs and SKU groups — the product taxonomy that plans price against - name: Chatbot description: Conversational endpoints - name: Collections description: '' - name: Contracts description: Contracts that bind a customer to one or more billing plans - name: Customers description: Manage customer records — the parties Enso bills - name: Email templates description: Manage email templates - name: Entities description: Entities (legal entity, contracting organisation) used in billing - name: Events description: Raw event ingestion — the input to the metering pipeline - name: FSM (object lifecycle) description: >- Drive lifecycle transitions on Invoice/Contract/etc. — used for raise, send, mark-paid, etc. - name: FX Rates description: Currency conversion rates - name: Geography description: Country/state lookups — reference data for addresses - name: Invoices description: Invoice CRUD, items, sync, PDF generation, document upload - name: Jobs description: >- Background job orchestration — used by long-running operations like bulk sync - name: Masters description: '' - name: Meters description: Usage meters — the per-aggregation tally that feeds invoices - name: Objects description: Generic object schema and query — exposes the data model dynamically - name: Organisation description: '' - name: Organisation attributes description: Organisation-level custom attributes - name: Organisation settings description: Organisation-wide configuration values - name: Revenue description: Recognised revenue records derived from invoices - name: Usage description: Usage records — what got billed against each meter for a billing period - name: Users description: User account read access paths: /entities/list: get: tags: - Entities summary: Get list description: >- Get a paginated list of customer entities with selectable attributes, filtering, grouping, and sorting. operationId: getEntitiesByTypeWithFilters parameters: - name: page in: query description: Page number for pagination. required: false schema: type: integer default: 1 minimum: 1 - name: limit in: query description: Number of entities per page. required: false schema: type: integer default: 10 minimum: 1 maximum: 100 - name: filters in: query description: >- Filters to apply. Pass as a **URL-encoded JSON string**. **Example usage in query string:** `filters=%7B%22entityFor%22%3A%22customer%22%7D` **Example usage in code:** ```js filters: encodeURIComponent(JSON.stringify({ entityFor: "customer" })) ``` required: false schema: type: string - name: attributes in: query description: >- List of attributes to return. Pass as a **URL-encoded JSON array**. **Example usage in query string:** `attributes=%5B%22id%22%2C%22legalName%22%2C%22bankDetails%22%2C%22alias%22%2C%22Addresses.address1%22%2C%22Addresses.address2%22%2C%22Addresses.city%22%2C%22Addresses.zip%22%2C%22Addresses.State.name%22%2C%22Addresses.State.Country.name%22%2C%22email%22%2C%22phoneNumber%22%2C%22cc%22%2C%22bcc%22%2C%22Customer.name%22%2C%22entityForId%22%2C%22contractCount%22%5D` required: false schema: type: string - name: groupBy in: query description: |- Fields to group by. Pass as a **URL-encoded JSON array**. **Example usage in query string:** `groupBy=%5B%22Entity.id%22%2C%22Addresses.id%22%5D` required: false schema: type: string - name: sortBy in: query description: Field to sort by. required: false schema: type: string example: createdAt - name: sortOrder in: query description: Sort order. required: false schema: type: string enum: - asc - desc example: desc - name: search in: query schema: type: string description: Search/filter string responses: '200': description: Success. Returns a paginated list of customer entities. content: application/json: schema: type: object properties: status: type: string message: type: string data: type: object properties: rows: type: array items: type: object properties: id: type: string legalName: type: string bankDetails: type: string alias: type: string email: type: array items: type: string phoneNumber: type: string cc: type: array items: type: string bcc: type: array items: type: string entityForId: type: string contractCount: type: integer Customer: type: object properties: name: type: string Addresses: type: array items: type: object properties: address1: type: string address2: type: string city: type: string zip: type: string State: type: object properties: name: type: string Country: type: object properties: name: type: string count: type: integer examples: success: value: status: success message: Success data: rows: - id: ent_123 legalName: Acme Inc bankDetails: Bank of Example - ****1234 alias: acme email: - billing@acme.test phoneNumber: +1-415-555-0100 cc: - finance@acme.test bcc: - audit@acme.test Customer: name: Acme Customer entityForId: cus_123 contractCount: 4 Addresses: - address1: 123 Market St address2: Suite 200 city: San Francisco zip: '94105' State: name: California Country: name: United States count: 1 '400': description: Bad request. Invalid parameters or processing error. content: application/json: examples: error: value: status: error message: Error errors: - Invalid parameters data: {} '401': description: Unauthorized — token missing or invalid '403': description: Forbidden — insufficient permissions components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token obtained from POST /auth/system-login using your client credentials. ````