GET
/
contacts
Get Contacts
curl --request GET \
  --url https://api.clemta.com/contacts \
  --header 'X-API-Key: <api-key>'
{
  "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]",
          "[email protected]"
        ],
        "bcc_emails": [
          "[email protected]",
          "[email protected]"
        ],
        "billing": {
          "email": "[email protected]",
          "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"
        }
      }
    ],
    "total": 123
  }
}

​
List Contacts

This endpoint allows you to retrieve a list of contacts for a company with optional filtering and pagination.

​
Headers

ParameterTypeDescription
X-API-KEYstringFormation API Key (required)

​
Query Parameters

ParameterTypeRequiredDescription
company_idstringYesCompany ID to filter contacts
skipstringNoNumber of records to skip (pagination)
limitstringNoNumber of records to return (pagination)
searchstringNoSearch term to filter contacts
sortstringNoField to sort by
orderstringNoSort order: “asc” or “desc”
created_atstringNoCreated at filter
created_at_valuestringNoCreated at value
end_datestringNoEnd 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

{
  "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": "[email protected]",
        "description": "Primary customer contact",
        "cc_emails": ["[email protected]"],
        "bcc_emails": ["[email protected]"],
        "billing": {
          "email": "[email protected]",
          "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

ParameterTypeDescription
successbooleanIndicates if the operation was successful
messagestringAdditional information about the operation
dataobjectResponse data for successful requests
data.contactsarrayArray of contact objects
data.totalintegerTotal number of contacts
data.skipintegerNumber of records skipped
data.limitintegerNumber of records returned

​
Contact Object Fields

FieldTypeDescription
idstringUnique identifier for the contact
created_atintegerCreation timestamp
updated_atintegerLast update timestamp
typestringContact type (“customer” or “vendor”)
statusstringContact status
full_namestringFull name of the contact
emailstringEmail address
descriptionstringContact description
cc_emailsarrayCC email addresses
bcc_emailsarrayBCC email addresses
billingobjectBilling information

​
Error Responses

​
Invalid Request (400)

{
  "success": false,
  "message": "Invalid request data",
  "error": {
    "code": "INVALID_REQUEST",
    "details": "Company ID is required"
  }
}

​
Unauthorized (401)

{
  "success": false,
  "message": "API key is required",
  "error": {
    "code": "API_KEY_REQUIRED"
  }
}

​
Company Not Found (404)

{
  "success": false,
  "message": "Company not found",
  "error": {
    "code": "COMPANY_NOT_FOUND"
  }
}

​
Internal Server Error (500)

{
  "success": false,
  "message": "Internal server error",
  "error": {
    "code": "INTERNAL_ERROR"
  }
}

Authorizations

​
X-API-Key
string
header
required

Formation API key for authentication.

Query Parameters

​
company_id
string
required

Company ID

​
skip
string

Number of records to skip

​
limit
string

Number of records to return

​
search
string

Search term

​
sort
string

Sort field

​
order
enum<string>

Sort order (asc/desc)

Available options:
asc,
desc
​
created_at
string

Created at filter

​
created_at_value
string

Created at value

​
end_date
string

End date filter

Response

200
application/json

Contacts retrieved successfully

The response is of type object.