> ## Documentation Index > Fetch the complete documentation index at: https://docs.tetherai.ca/llms.txt > Use this file to discover all available pages before exploring further. # List contacts by pipeline status buckets > Returns contacts grouped by pipeline status / stage, supporting per-bucket pagination via the `page` map. Used by the Kanban board to fetch each column. Honors the same ownership, search, and advanced filters as the flat list endpoint. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/contacts openapi: 3.0.3 info: title: Tether Relay and Tether API version: 1.0.0 description: >- Route-derived OpenAPI contract generated from tether-relay backend sources. Regenerate with scripts/sync-openapi-from-backend.mjs. servers: - url: https://your-instance.example.com description: Production - url: http://localhost:2212 description: Local API service security: [] tags: - name: AI - name: Applications - name: Approval - name: Auth - name: Automations - name: Calls - name: Campaigns - name: Contact Analytics - name: Contact Metrics - name: Contact Notes - name: Contacts - name: Conversation Monitor - name: Conversations - name: Departments - name: Email - name: Escalation Dashboard - name: Event Logs - name: Google Sheets - name: Marketplace - name: Messages - name: Notification Sounds - name: Notifications - name: Org Snapshots - name: Organizations - name: Outreach - name: Outreach Metrics - name: Outreach Sources - name: Pipelines - name: Processes - name: Prompts - name: Reminders - name: Sms - name: Templates - name: Traces - name: Training - name: Upload - name: User Snapshots - name: Users - name: Vertical - name: Webchats - name: Webhook paths: /api/contacts: post: tags: - Contacts summary: List contacts by pipeline status buckets description: >- Returns contacts grouped by pipeline status / stage, supporting per-bucket pagination via the `page` map. Used by the Kanban board to fetch each column. Honors the same ownership, search, and advanced filters as the flat list endpoint. operationId: post_contacts requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GetContactsPerStatusRequest' responses: '200': description: Contacts grouped by status content: application/json: schema: $ref: '#/components/schemas/ContactsByStageResponse' '404': description: Pipeline not found content: application/json: schema: $ref: '#/components/schemas/LegacyErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/LegacyErrorResponse' security: - bearerAuth: [] components: schemas: GetContactsPerStatusRequest: type: object properties: page: type: object additionalProperties: type: integer description: >- Per-stage page numbers keyed by stage id or stage name (e.g. `{ "New Lead": 2 }`). size: type: integer description: Page size applied to every stage query. search: type: string description: >- Case-insensitive substring match across first/last name, full name, and phone-number value. source: type: string description: >- Filter to contacts whose `source` equals this value (Contacts pipeline only). ownerFilter: type: string description: >- Quick-tab owner scope: `my`, `all`, `team`, `unassigned`, or a specific user `_id`. owner: type: array items: type: string description: >- Specific-tab owner ids — matches contacts where any listed user is creator, owner, or assignee. Overrides `ownerFilter`. assignee: type: array items: type: string description: >- Restrict to contacts whose conversations have any of these users as assignees. pipelineType: type: string enum: - Contact - Application description: Which model to query; defaults to `Contact`. pipelineId: type: string description: >- Specific pipeline `_id` to query; falls back to the org's active pipeline of `pipelineType`. status: type: string description: >- When set, restrict the result to this single stage (by name or id) instead of returning all stages. dateRange: type: object additionalProperties: true description: >- Legacy `{ start, end }` createdAt window; kept for backward compatibility — prefer `createdDateRange`. createdDateRange: type: object additionalProperties: true description: '`{ start, end }` ISO range filtering on `createdAt`.' customFilters: type: object additionalProperties: true description: >- Map of custom-field key to value; string values use case-insensitive regex match. stages: type: array items: type: string description: >- Client-provided stage names to avoid a pipeline lookup; ordering controls which stages get queried. stageIdByName: type: object additionalProperties: type: string description: >- Optional stage-name to stage-id map enabling indexed `pipelineStage` queries instead of legacy status-name filters. bulkOnly: type: boolean description: 'Restrict to contacts created via bulk import (`isBulkSms: true`).' messageStatus: type: string description: >- Message engagement filter: `all`, `answered` (has any message), or `unanswered`. lastMessageTimeRange: type: object additionalProperties: true description: >- `{ value, unit }` (hours/days) — returns contacts with NO messages within that recent window. lastMessageDateRange: type: object additionalProperties: true description: >- `{ start, end }` window — returns contacts whose messages fall within this absolute date range. additionalProperties: true example: page: New Lead: 1 Qualified: 1 size: 25 search: jane ownerFilter: my pipelineType: Contact pipelineId: 64f0a1b2c3d4e5f6a7b8c9d1 ContactsByStageResponse: type: object properties: data: type: object additionalProperties: type: object properties: contacts: type: array items: $ref: '#/components/schemas/ContactDto' total: type: integer additionalProperties: true dataByStatus: type: object additionalProperties: true stageIdByName: type: object additionalProperties: type: string stageNameById: type: object additionalProperties: type: string additionalProperties: true example: data: New Lead: contacts: [] total: 12 Qualified: contacts: [] total: 4 stageIdByName: New Lead: 64f0a1b2c3d4e5f6a7b8c9d2 LegacyErrorResponse: type: object properties: error: type: string message: type: string data: {} additionalProperties: true example: error: Attachment not found message: Attachment not found ContactDto: type: object properties: _id: type: string firstName: type: string nullable: true lastName: type: string nullable: true phoneNumber: nullable: true oneOf: - type: string - type: array items: $ref: '#/components/schemas/ContactPhoneNumber' secondaryPhoneNumber: type: array nullable: true items: type: string email: type: string nullable: true status: type: string nullable: true pipelineId: type: string nullable: true pipelineStage: type: string nullable: true organizationId: type: string nullable: true userId: type: string nullable: true createdBy: type: string nullable: true assignees: type: array items: {} createdAt: type: string format: date-time nullable: true updatedAt: type: string format: date-time nullable: true existingConversationId: type: string nullable: true description: >- Set on responses from /api/contacts/inactive when called with includeExisting=true. Identifies the caller-accessible conversation in the requested channel; clients should route to this conversation instead of creating a new one. additionalProperties: true example: _id: 64f0a1b2c3d4e5f6a7b8c9d0 firstName: Jane lastName: Doe phoneNumber: - value: '+14165550100' isPrimary: true secondaryPhoneNumber: [] email: jane.doe@example.com status: New Lead pipelineId: 64f0a1b2c3d4e5f6a7b8c9d1 pipelineStage: 64f0a1b2c3d4e5f6a7b8c9d2 organizationId: 64f0a1b2c3d4e5f6a7b8c9d3 userId: 64f0a1b2c3d4e5f6a7b8c9d4 createdBy: 64f0a1b2c3d4e5f6a7b8c9d4 assignees: - 64f0a1b2c3d4e5f6a7b8c9d4 createdAt: '2026-05-01T14:30:00.000Z' updatedAt: '2026-05-15T09:12:00.000Z' ContactPhoneNumber: type: object properties: value: type: string isPrimary: type: boolean required: - value additionalProperties: true example: value: '+14165550100' isPrimary: true securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````