> ## Documentation Index > Fetch the complete documentation index at: https://docs.clemta.com/llms.txt > Use this file to discover all available pages before exploring further. # List Contacts > Retrieve a list of contacts with filtering and pagination # List Contacts This endpoint allows you to retrieve a list of contacts for a company with optional filtering and pagination. ## Headers | Parameter | Type | Description | | --------- | ------ | ---------------------------- | | X-API-KEY | string | Formation API Key (required) | ## Query Parameters | Parameter | Type | Required | Description | | ------------------ | ------ | -------- | ---------------------------------------- | | company\_id | string | Yes | Company ID to filter contacts | | skip | string | No | Number of records to skip (pagination) | | limit | string | No | Number of records to return (pagination) | | search | string | No | Search term to filter contacts | | sort | string | No | Field to sort by | | order | string | No | Sort order: "asc" or "desc" | | created\_at | string | No | Created at filter | | created\_at\_value | string | No | Created at value | | end\_date | string | No | End date filter | ### Parameter Examples * **Basic request**: `GET /contacts?company_id=64b8f1a2e4b0c8d9f0123456` * **With pagination**: `GET /contacts?company_id=64b8f1a2e4b0c8d9f0123456&skip=0&limit=10` * **With search**: `GET /contacts?company_id=64b8f1a2e4b0c8d9f0123456&search=john` * **With sorting**: `GET /contacts?company_id=64b8f1a2e4b0c8d9f0123456&sort=created_at&order=desc` ## Response ```json theme={null} { "success": true, "message": "Contacts retrieved successfully", "data": { "contacts": [ { "id": "64b8f1a2e4b0c8d9f0123456", "created_at": 1686787200, "updated_at": 1686787200, "type": "customer", "status": "active", "full_name": "John Doe", "email": "john.doe@example.com", "description": "Primary customer contact", "cc_emails": ["billing@example.com"], "bcc_emails": ["admin@example.com"], "billing": { "email": "billing@example.com", "phone": "+1234567890", "phone_code": "+1", "iso_code": "US", "country": "United States", "address_1": "123 Main St", "address_2": "Suite 100", "postal_code": "12345", "district": "Downtown", "state": "CA", "province": "California", "tax_id": "12-3456789" } } ], "total": 1, "skip": 0, "limit": 10 } } ``` ### Response Parameters | Parameter | Type | Description | | ------------- | ------- | ------------------------------------------ | | success | boolean | Indicates if the operation was successful | | message | string | Additional information about the operation | | data | object | Response data for successful requests | | data.contacts | array | Array of contact objects | | data.total | integer | Total number of contacts | | data.skip | integer | Number of records skipped | | data.limit | integer | Number of records returned | ### Contact Object Fields | Field | Type | Description | | ----------- | ------- | ------------------------------------- | | id | string | Unique identifier for the contact | | created\_at | integer | Creation timestamp | | updated\_at | integer | Last update timestamp | | type | string | Contact type ("customer" or "vendor") | | status | string | Contact status | | full\_name | string | Full name of the contact | | email | string | Email address | | description | string | Contact description | | cc\_emails | array | CC email addresses | | bcc\_emails | array | BCC email addresses | | billing | object | Billing information | ## Error Responses ### Invalid Request (400) ```json theme={null} { "success": false, "message": "Invalid request data", "error": { "code": "INVALID_REQUEST", "details": "Company ID is required" } } ``` ### Unauthorized (401) ```json theme={null} { "success": false, "message": "API key is required", "error": { "code": "API_KEY_REQUIRED" } } ``` ### Company Not Found (404) ```json theme={null} { "success": false, "message": "Company not found", "error": { "code": "COMPANY_NOT_FOUND" } } ``` ### Internal Server Error (500) ```json theme={null} { "success": false, "message": "Internal server error", "error": { "code": "INTERNAL_ERROR" } } ``` ## OpenAPI ````yaml GET /contacts openapi: 3.0.3 info: title: Clemta Formation API description: >- API for company formation services. This API allows partners to create, retrieve, and manage company formations programmatically. version: '2025-06-24' contact: name: Clemta API Support email: tech@clemta.com license: name: Proprietary url: https://clemta.com/terms servers: - url: https://api.clemta.com description: Production server - url: https://sandbox.clemta.com description: Sandbox server security: - ApiKeyAuth: [] paths: /contacts: get: tags: - Contacts summary: Get Contacts description: >- Retrieves a list of contacts for a company with optional filtering and pagination operationId: getContacts parameters: - name: company_id in: query required: true description: Company ID schema: type: string - name: skip in: query required: false description: Number of records to skip schema: type: string - name: limit in: query required: false description: Number of records to return schema: type: string - name: search in: query required: false description: Search term schema: type: string - name: sort in: query required: false description: Sort field schema: type: string - name: order in: query required: false description: Sort order (asc/desc) schema: type: string enum: - asc - desc - name: created_at in: query required: false description: Created at filter schema: type: string - name: created_at_value in: query required: false description: Created at value schema: type: string - name: end_date in: query required: false description: End date filter schema: type: string responses: '200': description: Contacts retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ContactListResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '404': description: Company not found content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' components: schemas: ContactListResponse: type: object properties: success: type: boolean example: true message: type: string example: Contacts retrieved successfully data: type: object properties: contacts: type: array items: $ref: '#/components/schemas/ContactResponse' total: type: integer description: Total number of contacts BadRequestError: type: object properties: success: type: boolean example: false message: type: string example: Invalid request data data: type: object nullable: true example: null error: type: object properties: code: type: string example: INVALID_REQUEST details: type: string example: Field 'name' is required UnauthorizedError: type: object properties: success: type: boolean example: false message: type: string example: API key is required data: type: object nullable: true example: null error: type: object properties: code: type: string example: API_KEY_REQUIRED details: type: string example: '' NotFoundError: type: object properties: success: type: boolean example: false message: type: string example: Company not found data: type: object nullable: true example: null error: type: object properties: code: type: string example: COMPANY_NOT_FOUND details: type: string example: '' InternalServerError: type: object properties: success: type: boolean example: false message: type: string example: Internal server error data: type: object nullable: true example: null error: type: object properties: code: type: string example: INTERNAL_ERROR details: type: string example: An unexpected error occurred. ContactResponse: type: object example: id: 64b8f1a2e4b0c8d9f0123456 created_at: 1640995200 updated_at: 1640995200 type: customer status: active full_name: John Doe email: john.doe@example.com description: Primary contact for the company cc_emails: - cc1@example.com - cc2@example.com bcc_emails: - bcc1@example.com - bcc2@example.com billing: email: billing@example.com phone: '1234567890' phone_code: '+1' iso_code: US country: United States address_1: 123 Main Street address_2: Suite 100 postal_code: '12345' district: Downtown state: CA province: California tax_id: 12-3456789 properties: id: type: string description: Contact ID created_at: type: integer description: Creation timestamp updated_at: type: integer description: Last update timestamp type: type: string enum: - customer - vendor description: Contact type status: type: string description: Contact status full_name: type: string description: Full name email: type: string description: Email address description: type: string description: Description cc_emails: type: array items: type: string description: CC email addresses bcc_emails: type: array items: type: string description: BCC email addresses billing: $ref: '#/components/schemas/ContactBilling' ContactBilling: type: object properties: email: type: string description: Billing email address phone: type: string description: Phone number phone_code: type: string description: Phone country code iso_code: type: string description: Country ISO code country: type: string description: Country name address_1: type: string description: Address line 1 address_2: type: string description: Address line 2 postal_code: type: string description: Postal code district: type: string description: District state: type: string description: State province: type: string description: Province tax_id: type: string description: Tax ID securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Formation API key for authentication. ````