> ## Documentation Index > Fetch the complete documentation index at: https://docs.heffl.com/llms.txt > Use this file to discover all available pages before exploring further. # List companies > Returns a paginated list of company records. Supports cursor pagination, full-text search, structured filters (stage, owner, tags, dates), and sorting. Results respect the API key user's ownership permissions. See the [Listing & filters](/api-v2/listing-and-filters) guide for filter syntax. ## OpenAPI ````yaml /openapi.v2.json get /companies openapi: 3.1.1 info: title: Heffl API v2 (Beta) version: 2.0.0 description: >- Heffl REST API v2 (beta) — resource-oriented endpoints with consistent response envelopes. Endpoints, schemas, and behavior may change until GA. See Agent workflows and ID prefixes guides for automation. contact: name: Heffl Support url: https://heffl.com/support email: support@heffl.com servers: - url: https://api.heffl.com/api/v2 description: Production API Server security: - ApiKeyAuth: [] paths: /companies: get: tags: - Objects summary: List companies description: >- Returns a paginated list of company records. Supports cursor pagination, full-text search, structured filters (stage, owner, tags, dates), and sorting. Results respect the API key user's ownership permissions. See the [Listing & filters](/api-v2/listing-and-filters) guide for filter syntax. operationId: objects.companies.list parameters: - name: cursor in: query required: false schema: type: string description: >- Cursor for pagination. Pass the previous response meta.nextCursor value to fetch the next page. - name: pageSize in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 30 description: Number of items to return per page (max 100) - name: search in: query required: false schema: type: string description: Search by name, number, email, or phone - name: orderBy in: query required: false schema: type: string enum: - createdAt - name - number default: createdAt description: Field to sort results by - name: orderDir in: query required: false schema: type: string enum: - asc - desc default: desc description: Sort direction - name: filters in: query required: false schema: type: object description: >- Structured filters. Each key is a filter field with operator and values. Option fields use string IDs; date fields use ISO 8601 date-time strings. See the Listing & filters guide. style: deepObject explode: true responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Company' meta: type: object properties: nextCursor: type: - string - 'null' description: Cursor to fetch the next page hasMore: type: boolean description: Whether additional results are available required: - hasMore required: - data - meta '400': description: Validation error or bad request content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '403': description: Insufficient permission content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/V2ApiError' components: schemas: Company: type: object properties: id: type: string description: Company ID name: type: string description: Company name number: type: string description: Auto-generated company number type: anyOf: - type: string enum: - contact - company - type: 'null' description: Record type (always company for this endpoint) email: anyOf: - type: string - type: 'null' description: Email address phone: anyOf: - type: string - type: 'null' description: Phone number taxNumber: anyOf: - type: string - type: 'null' description: Tax number website: anyOf: - type: string - type: 'null' description: Website URL description: anyOf: - type: string - type: 'null' description: Description stageId: anyOf: - type: string - type: 'null' description: Client stage ID stageName: anyOf: - type: string - type: 'null' description: Client stage label ownerUserId: anyOf: - type: string - type: 'null' description: Owner user ID crmSourceId: anyOf: - type: string - type: 'null' description: CRM source ID sourceName: anyOf: - type: string - type: 'null' description: CRM source name currency: anyOf: - type: string - type: 'null' description: Currency code openingBalance: type: number description: Opening balance showJobAmountToWorker: type: boolean description: Whether job amounts are visible to field workers isClientPortalEnabled: type: boolean description: Whether the client portal is enabled internalNotes: anyOf: - type: string - type: 'null' description: Internal notes linkedin: anyOf: - type: string - type: 'null' description: LinkedIn URL createdAt: type: string format: date-time description: When the company was created updatedAt: type: string format: date-time description: When the company was last updated required: - id - name - number - openingBalance - showJobAmountToWorker - isClientPortalEnabled additionalProperties: description: >- Custom field values as top-level cf_* keys (for example cf_industry). There is no customFields wrapper. V2ApiError: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: object securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key for authentication. Get yours at app.heffl.com/settings/developers ````