Skip to main content
GET
/
contacts
List Contacts
curl --request GET \
  --url https://api.clemta.com/contacts
{
  "success": true,
  "message": "<string>",
  "data": {
    "contacts": [
      {
        "id": "<string>",
        "created_at": 123,
        "updated_at": 123,
        "type": "<string>",
        "status": "<string>",
        "full_name": "<string>",
        "email": "<string>",
        "description": "<string>",
        "cc_emails": [
          {}
        ],
        "bcc_emails": [
          {}
        ],
        "billing": {}
      }
    ],
    "total": 123
  }
}

​
Authentication

This endpoint requires authentication using an API key. Include your API key in the request header: 
X-API-Key: your_api_key_here
See Authentication for more details.

​
Query Parameters

​
company_id
string
required
The ID of the company to retrieve contacts for.
​
skip
string
Number of records to skip for pagination. Defaults to 0.
​
limit
string
Number of records to return. Defaults to a system-defined limit.
​
search
string
Search term to filter contacts by name or email.
​
sort
string
Field to sort by (e.g., full_name, email, created_at).
​
order
string
Sort order. Must be either asc (ascending) or desc (descending).
​
created_at
string
Filter operator for created_at field (e.g., gt, lt, eq).
​
created_at_value
string
Timestamp value for created_at filter (Unix timestamp).
​
end_date
string
End date for date range filtering (Unix timestamp).

​
Response

​
success
boolean
Indicates if the request was successful.
​
message
string
Response message.
​
data
object
Response data containing the list of contacts.

​
HTTP Response Codes

CodeDescription
200Contacts retrieved successfully
400Invalid request
401Unauthorized - Invalid or missing API key
404Company not found
500Internal server error

​
Error Response

When an error occurs, the API returns an error response: 
{
  "success": false,
  "message": "Invalid request",
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "details": "company_id is required"
  }
}

​
Code Examples

curl -X GET "https://api.clemta.com/contacts?company_id=64b8f1a2e4b0c8d9f0123456&limit=10&skip=0&sort=full_name&order=asc" \
  -H "X-API-Key: your_api_key_here"

​
Example Response

{
  "success": true,
  "message": "Contacts retrieved successfully",
  "data": {
    "contacts": [
      {
        "id": "64b8f1a2e4b0c8d9f0123456",
        "created_at": 1640995200,
        "updated_at": 1640995200,
        "type": "customer",
        "status": "active",
        "full_name": "John Doe",
        "email": "[email protected]",
        "description": "Primary contact for the company",
        "cc_emails": ["[email protected]"],
        "bcc_emails": [],
        "billing": {
          "email": "[email protected]",
          "phone": "1234567890",
          "phone_code": "+1",
          "iso_code": "US",
          "country": "United States",
          "address_1": "123 Main Street",
          "postal_code": "12345",
          "state": "CA"
        }
      },
      {
        "id": "64b8f1a2e4b0c8d9f0123457",
        "created_at": 1641081600,
        "updated_at": 1641081600,
        "type": "vendor",
        "status": "active",
        "full_name": "Jane Smith",
        "email": "[email protected]",
        "description": "Office supplies vendor",
        "cc_emails": [],
        "bcc_emails": [],
        "billing": {
          "email": "[email protected]",
          "phone": "9876543210",
          "phone_code": "+1",
          "iso_code": "US",
          "country": "United States",
          "address_1": "456 Vendor Ave",
          "postal_code": "54321",
          "state": "NY"
        }
      }
    ],
    "total": 2
  }
}

​
Pagination Example

To paginate through contacts, use the skip and limit parameters: 
# Get first page (10 items)
curl -X GET "https://api.clemta.com/contacts?company_id=64b8f1a2e4b0c8d9f0123456&limit=10&skip=0" \
  -H "X-API-Key: your_api_key_here"

# Get second page (10 items)
curl -X GET "https://api.clemta.com/contacts?company_id=64b8f1a2e4b0c8d9f0123456&limit=10&skip=10" \
  -H "X-API-Key: your_api_key_here"

​
Search Example

To search for contacts by name or email: 
curl -X GET "https://api.clemta.com/contacts?company_id=64b8f1a2e4b0c8d9f0123456&search=john" \
  -H "X-API-Key: your_api_key_here"

Build docs developers (and LLMs) love

Get started for freeTalk to us