> ## 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 contacts > Returns a paginated list of contact 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 /contacts 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: /contacts: get: tags: - Objects summary: List contacts description: >- Returns a paginated list of contact 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.contacts.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. properties: stageId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Client stage ID (e.g. cs_abc123 or lstg_abc123) leadStageId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Lead stage ID (e.g. lstg_abc123) ownerUserId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Owner user ID (e.g. usr_abc123) createdById: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Creator user ID (e.g. usr_abc123) listId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: List ID (e.g. lst_abc123) tagId: type: object properties: operator: type: string enum: - include - exclude - include_any_of - include_all_of - exclude_if_any_of - exclude_if_all values: type: array items: type: string description: Tag ID (e.g. tag_abc123) createdAt: type: object properties: operator: type: string enum: - is - is_not - is_before - is_after - is_on_or_before - is_on_or_after - is_between - is_not_between values: type: array items: type: string format: date-time style: deepObject explode: true responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Contact' 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: Contact: type: object properties: id: type: string description: Contact person's ID (clt_ prefix) name: type: string description: Display name number: type: string description: Auto-generated contact number type: anyOf: - type: string enum: - contact - company - type: 'null' description: Record type (always contact for this endpoint) firstName: type: string description: First name lastName: anyOf: - type: string - type: 'null' description: Last name email: anyOf: - type: string - type: 'null' description: Email address phone: anyOf: - type: string - type: 'null' description: Phone number salutation: anyOf: - type: string - type: 'null' description: Salutation jobTitle: anyOf: - type: string - type: 'null' description: Job title description: anyOf: - type: string - type: 'null' description: Description taxNumber: anyOf: - type: string - type: 'null' description: Tax number website: anyOf: - type: string - type: 'null' description: Website URL companyId: anyOf: - type: string - type: 'null' description: Parent company ID companyName: anyOf: - type: string - type: 'null' description: Parent company name parentClientId: anyOf: - type: string - type: 'null' description: Parent client ID (same as companyId for contacts) stageId: anyOf: - type: string - type: 'null' description: Client stage ID stageName: anyOf: - type: string - type: 'null' description: Client stage label leadStageId: anyOf: - type: string - type: 'null' description: Lead stage ID 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 profileImage: anyOf: - type: string - type: 'null' description: Profile image URL instagram: anyOf: - type: string - type: 'null' description: Instagram handle or URL facebook: anyOf: - type: string - type: 'null' description: Facebook handle or URL linkedin: anyOf: - type: string - type: 'null' description: LinkedIn handle or URL twitter: anyOf: - type: string - type: 'null' description: Twitter handle or URL createdAt: type: string format: date-time description: When the contact was created updatedAt: type: string format: date-time description: When the contact was last updated required: - id - name - number - firstName - 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 ````