> ## Documentation Index > Fetch the complete documentation index at: https://docs.alvahq.com/llms.txt > Use this file to discover all available pages before exploring further. # List contacts > Retrieve a paginated list of contacts. Supports search and filtering. ## OpenAPI ````yaml https://app.alvahq.com/api/v1/openapi get /api/v1/contacts openapi: 3.1.0 info: title: Alva API version: 1.0.0 description: > The Alva API provides programmatic access to your CRM data. Use it to integrate Alva with other applications, build custom workflows, or connect via platforms like Zapier. ## Authentication All API requests require a valid API key passed as a Bearer token: ``` Authorization: Bearer alva_sk_your_api_key_here ``` API keys can be created and managed in **Settings > Developer** within the Alva application. ## Rate Limiting API requests are rate limited to **100 requests per minute** per API key. Rate limit information is included in response headers: - `X-RateLimit-Limit` - Maximum requests per minute - `X-RateLimit-Remaining` - Requests remaining in current window - `X-RateLimit-Reset` - Unix timestamp when the window resets ## Pagination List endpoints support pagination via query parameters: - `page` - Page number (default: 1) - `limit` - Items per page (default: 25, max: 100) ## Sorting List endpoints support sorting: - `sort` - Sort field and direction, e.g. `sort=createdAt:desc` ## Errors All errors follow a consistent format: ```json { "error": "Error Type", "message": "Human-readable description", "details": { "field": ["Validation message"] } } ``` contact: name: Alva Support url: https://alva.ai servers: - url: https://app.alvahq.com description: Current environment security: - bearerAuth: [] tags: - name: Companies description: Manage companies in your CRM - name: Contacts description: Manage contacts and people - name: Deals description: Manage sales deals and pipeline - name: Activities description: Log and track activities (calls, meetings, emails, etc.) - name: Pipeline description: Pipeline stages and methodology metadata - name: Custom Fields description: Define custom fields on companies and contacts - name: Email Templates description: >- Manage email templates and template groups. Use {{company.custom.}} merge tags in subject and body. - name: Account description: API key, account members and company tags - name: BDR Agents description: List BDR agents and assign a company to one paths: /api/v1/contacts: get: tags: - Contacts summary: List contacts description: Retrieve a paginated list of contacts. Supports search and filtering. operationId: listContacts parameters: - name: page in: query schema: type: integer default: 1 minimum: 1 description: Page number - name: limit in: query schema: type: integer default: 25 minimum: 1 maximum: 100 description: Items per page (max 100) - name: sort in: query schema: type: string description: >- Sort by field:direction. Fields: firstName, lastName, email, createdAt, updatedAt. Direction: asc or desc. Example: createdAt:desc - name: search in: query schema: type: string description: Search by name or email - name: companyId in: query schema: type: string format: uuid description: Filter by company ID 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' resource: type: string '401': $ref: '#/components/responses/Unauthorised' '429': $ref: '#/components/responses/RateLimited' components: schemas: Contact: type: object properties: id: type: string format: uuid firstName: type: string example: Jane lastName: type: string example: Doe email: type: string nullable: true example: jane@acme.com companyId: type: string format: uuid nullable: true title: type: string nullable: true example: VP of Engineering phone: type: string nullable: true mobile: type: string nullable: true linkedin: type: string nullable: true twitter: type: string nullable: true notes: type: string nullable: true department: type: string nullable: true seniorityLevel: type: string nullable: true additionalEmails: type: array items: type: string additionalPhones: type: array items: type: string linkedinUrl: type: string nullable: true customFields: type: object nullable: true doNotContact: type: boolean doNotContactReason: type: string nullable: true doNotContactAt: type: string format: date-time nullable: true readOnly: true emailConfidence: type: integer nullable: true readOnly: true description: 0–100. Null when the address was not scored. companyVerified: type: boolean nullable: true readOnly: true seniorityScore: type: integer nullable: true readOnly: true isEconomicBuyer: type: boolean readOnly: true emailAvailable: type: boolean nullable: true readOnly: true phoneAvailable: type: boolean nullable: true readOnly: true mobileRevealStatus: type: string nullable: true readOnly: true inboundSource: type: string nullable: true readOnly: true createdById: type: string format: uuid nullable: true readOnly: true createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer totalPages: type: integer hasMore: type: boolean ErrorResponse: type: object properties: error: type: string message: type: string details: type: object nullable: true responses: Unauthorised: description: Authentication failed - invalid, expired, or revoked API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorised message: Invalid or revoked API key RateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Too Many Requests message: Rate limit exceeded. Maximum 100 requests per minute. retryAfter: 30 headers: Retry-After: schema: type: integer description: Seconds until rate limit resets securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'API key from Settings > Developer. Format: alva_sk_...' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.