GET
/
api
/
v1
/
contacts

​
Get Contacts

Retrieve a paginated list of contacts with various filtering options.

​
Endpoint

GET /api/v1/contacts

​
Authentication

This endpoint requires an API key with the can_read_contacts permission.

​
Query Parameters

ParameterTypeRequiredDescription
stagestringNoFilter by contact stage (lead, prospect, customer, etc.)
statusstringNoFilter by contact status (not_contacted, contacted, etc.)
tagstringNoFilter by tag name
searchstringNoSearch in first name, last name, and email
pageintegerNoPage number for pagination (default: 1)
limitintegerNoNumber of results per page (default: 25, max: 100)

​
Response

{
  "count": 157,
  "page": 1,
  "limit": 25,
  "pages": 7,
  "contacts": [
    {
      "id": 123,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "stage": "qualified_lead",
      "status": "contacted",
      "phone": "+15551234567",
      "created_date": "2025-03-15T10:30:00Z",
      "last_call_date": "2025-04-22T14:15:30Z",
      "tags": ["VIP", "Interested", "Follow-up"]
    },
    {
      "id": 124,
      "first_name": "Jane",
      "last_name": "Smith",
      "full_name": "Jane Smith",
      "email": "[email protected]",
      "company": "XYZ Inc",
      "stage": "customer",
      "status": "active",
      "phone": "+15559876543",
      "created_date": "2025-01-10T08:45:00Z",
      "last_call_date": "2025-04-20T11:30:00Z",
      "tags": ["Customer", "Enterprise"]
    }
  ]
}

​
Error Codes

Status CodeError CodeDescription
401authentication_requiredNo API key was provided
401invalid_keyThe API key is invalid or inactive
403permission_deniedThe API key doesn’t have the required permission
500server_errorAn unexpected server error occurred

​
Example Request

curl -X GET 'https://api.klen.ai/api/v1/contacts?stage=qualified_lead&tag=VIP&page=1&limit=25' \
  -H 'Authorization: Bearer klen_abcdef123456789'

​
Example Response

{
  "count": 12,
  "page": 1,
  "limit": 25,
  "pages": 1,
  "contacts": [
    {
      "id": 123,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "stage": "qualified_lead",
      "status": "contacted",
      "phone": "+15551234567",
      "created_date": "2025-03-15T10:30:00Z",
      "last_call_date": "2025-04-22T14:15:30Z",
      "tags": ["VIP", "Interested", "Follow-up"]
    }
  ]
}

​
Response Properties

PropertyTypeDescription
idintegerThe database ID of the contact
first_namestringFirst name of the contact
last_namestringLast name of the contact
full_namestringCombined first and last name
emailstringEmail address of the contact
companystringCompany or organization name
stagestringCurrent stage in the sales/contact pipeline
statusstringCurrent status of the contact
phonestringPrimary phone number of the contact
created_datestringISO 8601 date when the contact was created
last_call_datestringISO 8601 date of the most recent call with this contact
tagsarrayArray of tag names associated with the contact
teamobjectTeam information if the contact belongs to a team

​
Access Control

This endpoint returns contacts that the authenticated user has access to. This includes:

  1. Contacts created by the user
  2. Contacts belonging to teams that the user has access to