Skip to main content
POST
/
public-api
/
v1
/
contacts
/
exports
Create Contact Export
curl --request POST \
  --url https://app.cometly.com/public-api/v1/contacts/exports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "start_date": "<string>",
  "end_date": "<string>",
  "include_comet_tokens": true,
  "include_all_emails": true
}
'
{
  "export_id": 123,
  "status": "<string>",
  "message": "<string>"
}

​
Overview

This endpoint creates an asynchronous export job that generates a downloadable file containing contact data for a specific date range. The export is processed in the background and returns a presigned download URL when complete. Use this endpoint when you need to extract large volumes of contact data efficiently. For real-time needs, use the List Contacts endpoint instead.
When to use exports: Exports are ideal for bulk data extraction (10,000+ contacts). For smaller datasets, use the paginated list endpoint.

​
Request Body

​
Required Parameters

​
start_date
string
required
Start date and time for exporting contacts in YYYY-MM-DD HH:MM:SS format. Exports contacts created from this timestamp in your space’s timezone.Example: 2024-01-15 00:00:00
​
end_date
string
required
End date and time for exporting contacts in YYYY-MM-DD HH:MM:SS format. Must be after start_date. Exports contacts created until this timestamp in your space’s timezone.Example: 2024-01-15 23:59:59

​
Optional Parameters

​
include_comet_tokens
boolean
default:"0"
When set to 1, includes the last 5 comet tokens for each contact in the export file, ordered by most recent first. Accepts 1 or 0.
​
include_all_emails
boolean
default:"0"
When set to 1, includes all email addresses for each contact in the export file, including emails from merged profiles. Accepts 1 or 0.

​
Response

​
Success Response (202 Accepted)

​
export_id
integer
Unique identifier for the export job. Use this to check status with the Get Contact Export endpoint.
​
status
string
Current status of the export. Will be queued immediately after creation.

​
Error Response

​
message
string
Error description explaining what went wrong

​
Export File Format

Completed exports are delivered as gzipped NDJSON (Newline-Delimited JSON) files. Each line contains a complete JSON object representing one contact record. 
{"id":123,"email":"user@example.com","name":"John Doe","phone":"+1234567890","location":"US"}
{"id":124,"email":"jane@example.com","name":"Jane Smith","phone":"+9876543210","location":"CA"}
When include_comet_tokens=1 is specified: 
{"id":123,"email":"user@example.com","name":"John Doe","phone":"+1234567890","location":"US","comet_tokens":["token1","token2","token3"]}
{"id":124,"email":"jane@example.com","name":"Jane Smith","phone":"+9876543210","location":"CA","comet_tokens":["token4","token5"]}
When include_all_emails=1 is specified: 
{"id":123,"email":"user@example.com","name":"John Doe","phone":"+1234567890","location":"US","emails":["user@example.com","old@example.com"]}
{"id":124,"email":"jane@example.com","name":"Jane Smith","phone":"+9876543210","location":"CA","emails":["jane@example.com"]}
This format is ideal for streaming and processing large files line-by-line without loading the entire file into memory.

​
Example Requests

# Create export for a date range
curl -X POST "https://app.cometly.com/public-api/v1/contacts/exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-01-15 00:00:00",
    "end_date": "2024-01-15 23:59:59"
  }'

# Include comet tokens in export
curl -X POST "https://app.cometly.com/public-api/v1/contacts/exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-01-15 00:00:00",
    "end_date": "2024-01-15 23:59:59",
    "include_comet_tokens": 1
  }'

# Include all emails in export
curl -X POST "https://app.cometly.com/public-api/v1/contacts/exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-01-15 00:00:00",
    "end_date": "2024-01-15 23:59:59",
    "include_all_emails": 1
  }'

​
Status Codes

Status CodeDescription
202Export job created and queued for processing
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

​
Next Steps

After creating an export, poll the Get Contact Export endpoint to check the status and retrieve the download URL when ready.

​
Notes

  • Rate Limit: This endpoint has a limit of 5 requests per minute per Space. See Rate Limiting for details.
  • Processing Time: Exports typically complete within seconds to a few minutes depending on data volume
  • Date Range: Specify any date range using start_date and end_date (interpreted in your space’s timezone)
  • Export Capacity: Can handle 100,000+ contacts per export efficiently
  • Status Checking: Use the Get Contact Export endpoint to check status (30 requests/min limit)
  • File Expiration: Download URLs expire after 15 minutes for security. Retrieve the file promptly after completion.
  • Security: Export files use UUID-based filenames with time-limited presigned URLs to prevent unauthorized access
  • Date Filtering: Contacts are filtered by creation timestamp - only contacts created within the specified date range are included
  • Comet Tokens: Use the include_comet_tokens=1 parameter to include the last 5 comet tokens for each contact in the export file. This parameter is optional and defaults to 0.
  • All Emails: Use the include_all_emails=1 parameter to include all email addresses for each contact in the export file, including emails from merged profiles. This parameter is optional and defaults to 0.