Skip to main content
GET
https://app.cometly.com
/
public-api
/
v1
/
contacts
List Contacts
curl --request GET \
  --url https://app.cometly.com/public-api/v1/contacts \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {}
  ],
  "path": "<string>",
  "per_page": 123,
  "next_cursor": {},
  "next_page_url": {},
  "prev_cursor": {},
  "prev_page_url": {},
  "message": "<string>"
}

​
Overview

This endpoint allows you to retrieve a paginated list of contacts from Cometly within a specific date range. Each contact includes primary data from the profile (email, name, phone, location). For complete contact information including all associated emails, phones, names, and locations from merged profiles, use the individual contact endpoint GET /contacts/. Results are cursor-paginated for efficient data retrieval and ordered by ID (newest first).

​
Query Parameters

​
Required Parameters

​
start_date
string
required
Start date and time for filtering contacts by creation date in YYYY-MM-DD HH:MM:SS format. The date is interpreted in your space’s timezone.Example: 2024-01-15 00:00:00
​
end_date
string
required
End date and time for filtering contacts by creation date in YYYY-MM-DD HH:MM:SS format. Must be after start_date. The date is interpreted in your space’s timezone.Example: 2024-01-15 23:59:59

​
Optional Parameters

​
per_page
integer
default:"200"
Number of contacts to return per page. Minimum: 1, Maximum: 5000
​
cursor
string
Pagination cursor from a previous response. Use this to fetch the next page of results.
​
include_comet_tokens
boolean
default:"0"
When set to 1, includes the last 5 comet tokens for each contact, ordered by most recent first. Accepts 1 or 0.

​
Response

​
Success Response

The response follows Laravel’s cursor pagination structure:
​
data
array
Array of contact objects. Each contact includes:
  • id (integer): The unique identifier of the contact
  • email (string|null): Primary email address
  • name (string|null): Primary name
  • phone (string|null): Primary phone number
  • location (string|null): Primary location
  • comet_tokens (array): Array of comet tokens (only included when include_comet_tokens=1)
​
path
string
The base URL path for the endpoint
​
per_page
integer
Number of items per page
​
next_cursor
string | null
Cursor for the next page of results. null if there are no more pages.
​
next_page_url
string | null
Full URL for the next page of results. null if there are no more pages.
​
prev_cursor
string | null
Cursor for the previous page of results. null if on the first page.
​
prev_page_url
string | null
Full URL for the previous page of results. null if on the first page.

​
Error Response

​
message
string
Error description explaining what went wrong

​
Example Requests

# Basic request
curl -G "https://app.cometly.com/public-api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "start_date=2024-01-15 00:00:00" \
  -d "end_date=2024-01-15 23:59:59"

# Include comet tokens
curl -G "https://app.cometly.com/public-api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "start_date=2024-01-15 00:00:00" \
  -d "end_date=2024-01-15 23:59:59" \
  -d "include_comet_tokens=1"

# Pagination request using cursor
curl -G "https://app.cometly.com/public-api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "start_date=2024-01-15 00:00:00" \
  -d "end_date=2024-01-15 23:59:59" \
  -d "cursor=eyJpZCI6MTIzNDU..."

​
Status Codes

Status CodeDescription
200Contacts successfully retrieved
401Missing or invalid API key
403API key doesn’t have permission or subscription is inactive
422Invalid parameters provided (check error message for details)
429Too many requests - rate limit exceeded. See Rate Limiting

​
Notes

  • Rate Limit: This endpoint has a limit of 15 requests per minute per Space. See Rate Limiting for details.
  • Primary Data Only: This endpoint returns primary contact data (email, name, phone, location) from the profiles table for efficient browsing.
  • Complete Contact Data: For full contact information including all associated emails, phones, names, and locations from merged profiles, use GET /contacts/.
  • Performance: This endpoint uses a single efficient query, making it ideal for listing and browsing large numbers of contacts.
  • Ordering: Results are ordered by ID in descending order (newest first).
  • Pagination: Cursor pagination is used for efficient traversal of large result sets.
  • Comet Tokens: Use the include_comet_tokens=1 query parameter to include the last 5 comet tokens for each contact. This parameter is optional and defaults to 0.