> ## Documentation Index > Fetch the complete documentation index at: https://docs.talkpilot.io/llms.txt > Use this file to discover all available pages before exploring further. # List contacts > Returns the agent's contacts (customer database), newest first. Filter by an exact phone number (matched against `phone_number`, `mobile_number` and `landline_number`, like the voice agent does), by a tag, or by a free-text search over name, company, e-mail and numbers. ## OpenAPI ````yaml get /v1/agents/{agentId}/contacts openapi: 3.1.0 info: title: TalkPilot API version: 1.0.0 description: > The TalkPilot API allows you to programmatically manage your call center agents, employees, forwarding slots, knowledge base, and more. ## Authentication All API requests require an API key passed via the `X-API-Key` header: ``` X-API-Key: tp_live_abc123def456... ``` An API key can reach every organization its creator is a member of (see `GET /v1/organization`) and can be restricted to specific agents and permissions. Create and manage keys in the TalkPilot Dashboard under **Settings > API** (Dev-Admin only). ## Rate Limiting Default limits per API key: **60 requests/minute** and **1,000 requests/hour** (both enforced, both configurable per key). Rate limit headers are included in every response to a request authenticated with an API key (Dashboard JWT requests are not rate limited): - `X-RateLimit-Limit` — Max requests per minute - `X-RateLimit-Remaining` — Remaining requests in the current minute window - `X-RateLimit-Reset` — Unix timestamp roughly 60 seconds in the future When rate limited, the API returns `429 Too Many Requests` with `Retry-After: 60` (minute window) or `Retry-After: 3600` (hour window). ## Pagination List endpoints support pagination via query parameters: - `page` — Page number (default: 1) - `limit` — Items per page (default: 20, max: 100) Paginated responses include a `pagination` object with `page`, `limit`, `total`, and `pages`. ## Error Format All errors follow a consistent format: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human-readable description", "details": [{ "field": "name", "message": "Required" }], "request_id": "req_abc123" } } ``` contact: name: TalkPilot Support email: support@talkpilot.io license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.talkpilot.io description: Production security: - apiKey: [] tags: - name: Health description: API health and status - name: Agents description: Manage AI agent configurations - name: Workflow description: Multi-state conversation flow of an agent - name: Tools description: Manage agent tools (HTTP requests, call transfers, etc.) - name: Employees description: Manage employees linked to agents - name: Contacts description: >- Customer contacts (customer_database) per agent — the voice agent recognises callers and greets them by name or tag from here - name: Forwarding Slots description: Manage call forwarding slot assignments - name: Knowledge Base description: Manage agent knowledge base documents - name: Calls description: Read call records and transcripts - name: Organization description: Organization-level settings - name: API Keys description: Manage API keys (Dashboard JWT auth only; dev_admin) paths: /v1/agents/{agentId}/contacts: get: tags: - Contacts summary: List contacts description: | Returns the agent's contacts (customer database), newest first. Filter by an exact phone number (matched against `phone_number`, `mobile_number` and `landline_number`, like the voice agent does), by a tag, or by a free-text search over name, company, e-mail and numbers. operationId: listContacts parameters: - $ref: '#/components/parameters/AgentId' - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' - name: phone_number in: query description: Exact E.164 number; matches any of the three number fields schema: type: string example: '+491711234567' - name: tag in: query description: Only contacts carrying this tag (exact, case-sensitive) schema: type: string example: vip - name: search in: query description: >- Case-insensitive substring search over customer_name, company, email and the number fields schema: type: string responses: '200': description: List of contacts content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Contact' pagination: $ref: '#/components/schemas/Pagination' example: data: - id: 3f1c2a9e-5b7d-4e2f-9a1b-0c8d7e6f5a4b agent_id: 550e8400-e29b-41d4-a716-446655440000 customer_name: Herr Fey salutation: Herr first_name: null last_name: Fey name_parsed: manual name_source: manual phone_number: '+491711234567' mobile_number: '+491711234567' landline_number: '+492215550' email: fey@example.com address: Musterstraße 1, 50667 Köln company: Fey GmbH tags: - vip - stammkunde note: Bevorzugt Rückruf am Vormittag customer_number: 4711 last_contact_date: '2026-09-01T09:30:00Z' created_at: '2026-08-01T10:00:00Z' updated_at: '2026-09-01T09:30:00Z' pagination: page: 1 limit: 20 total: 1 pages: 1 '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: parameters: AgentId: name: agentId in: path required: true description: Agent UUID schema: type: string format: uuid PageParam: name: page in: query description: Page number schema: type: integer minimum: 1 default: 1 LimitParam: name: limit in: query description: Items per page schema: type: integer minimum: 1 maximum: 100 default: 20 schemas: Contact: type: object properties: id: type: string format: uuid agent_id: type: string format: uuid readOnly: true customer_name: type: - string - 'null' description: Display name, composed from the parts when they are given salutation: type: - string - 'null' example: Herr first_name: type: - string - 'null' last_name: type: - string - 'null' name_parsed: $ref: '#/components/schemas/NameParsed' name_source: type: string enum: - ai - manual readOnly: true description: >- `manual` = maintained by a person (API or Dashboard); the AI never overwrites such a name phone_number: type: - string - 'null' description: >- Primary number in E.164 — the voice agent matches callers against this and `mobile_number` mobile_number: type: - string - 'null' landline_number: type: - string - 'null' email: type: - string - 'null' format: email address: type: - string - 'null' company: type: - string - 'null' tags: type: - array - 'null' items: type: string description: >- Free tags; an agent's `greeting_variants` can pick a greeting per tag note: type: - string - 'null' customer_number: type: - number - 'null' last_contact_date: type: - string - 'null' format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer pages: type: integer NameParsed: type: string enum: - auto - llm - manual - unclear readOnly: true description: > Whether `salutation`/`first_name`/`last_name` are usable for a personal greeting. `manual` = parts sent explicitly, `auto` = split unambiguously from `customer_name`, `llm` = split by the backfill, `unclear` = not split (full name kept in `last_name`) — the voice agent then greets neutrally. Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - AGENT_NOT_ACCESSIBLE - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR message: type: string details: type: array items: type: object properties: field: type: string message: type: string request_id: type: string responses: ValidationError: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: Invalid request body details: - field: llm_temperature message: Must be between 0 and 2 request_id: req_abc123 Unauthorized: description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid or missing API key request_id: req_abc123 Forbidden: description: > Insufficient permissions (`FORBIDDEN`), or the agent is outside the key's `allowed_agent_ids` (`AGENT_NOT_ACCESSIBLE`) content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingPermission: value: error: code: FORBIDDEN message: 'API key lacks required permission: agents:write' request_id: req_abc123 agentNotAccessible: value: error: code: AGENT_NOT_ACCESSIBLE message: API key does not have access to this agent request_id: req_abc123 RateLimited: description: Too many requests for this API key (60/minute or 1,000/hour by default) headers: Retry-After: description: >- Seconds to wait before retrying — 60 for the minute window, 3600 for the hour window schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: Rate limit exceeded. Try again in 60 seconds. request_id: req_abc123 securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: | API key for external access. Format: `tp_live_<32-hex-chars>`. Create keys in the TalkPilot Dashboard under Settings > API. ````