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
}
'import requests
url = "https://app.cometly.com/public-api/v1/contacts/exports"
payload = {
"start_date": "<string>",
"end_date": "<string>",
"include_comet_tokens": True,
"include_all_emails": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
start_date: '<string>',
end_date: '<string>',
include_comet_tokens: true,
include_all_emails: true
})
};
fetch('https://app.cometly.com/public-api/v1/contacts/exports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.cometly.com/public-api/v1/contacts/exports",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'start_date' => '<string>',
'end_date' => '<string>',
'include_comet_tokens' => true,
'include_all_emails' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.cometly.com/public-api/v1/contacts/exports"
payload := strings.NewReader("{\n \"start_date\": \"<string>\",\n \"end_date\": \"<string>\",\n \"include_comet_tokens\": true,\n \"include_all_emails\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.cometly.com/public-api/v1/contacts/exports")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"start_date\": \"<string>\",\n \"end_date\": \"<string>\",\n \"include_comet_tokens\": true,\n \"include_all_emails\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.cometly.com/public-api/v1/contacts/exports")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"start_date\": \"<string>\",\n \"end_date\": \"<string>\",\n \"include_comet_tokens\": true,\n \"include_all_emails\": true\n}"
response = http.request(request)
puts response.read_body{
"export_id": 123,
"status": "<string>",
"message": "<string>"
}Contacts
Create Contact Export
Create an asynchronous export job to generate a downloadable file of contacts
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
}
'import requests
url = "https://app.cometly.com/public-api/v1/contacts/exports"
payload = {
"start_date": "<string>",
"end_date": "<string>",
"include_comet_tokens": True,
"include_all_emails": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
start_date: '<string>',
end_date: '<string>',
include_comet_tokens: true,
include_all_emails: true
})
};
fetch('https://app.cometly.com/public-api/v1/contacts/exports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.cometly.com/public-api/v1/contacts/exports",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'start_date' => '<string>',
'end_date' => '<string>',
'include_comet_tokens' => true,
'include_all_emails' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.cometly.com/public-api/v1/contacts/exports"
payload := strings.NewReader("{\n \"start_date\": \"<string>\",\n \"end_date\": \"<string>\",\n \"include_comet_tokens\": true,\n \"include_all_emails\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.cometly.com/public-api/v1/contacts/exports")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"start_date\": \"<string>\",\n \"end_date\": \"<string>\",\n \"include_comet_tokens\": true,\n \"include_all_emails\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.cometly.com/public-api/v1/contacts/exports")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"start_date\": \"<string>\",\n \"end_date\": \"<string>\",\n \"include_comet_tokens\": true,\n \"include_all_emails\": true\n}"
response = http.request(request)
puts response.read_body{
"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
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:00string
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:59Optional Parameters
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.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)
integer
Unique identifier for the export job. Use this to check status with the Get Contact Export endpoint.
string
Current status of the export. Will be
queued immediately after creation.Error Response
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"}
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"]}
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"]}
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
}'
// Create export for a date range
const response = await fetch('https://app.cometly.com/public-api/v1/contacts/exports', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
start_date: '2024-01-15 00:00:00',
end_date: '2024-01-15 23:59:59'
})
});
const data = await response.json();
console.log(`Export created: ${data.export_id}, Status: ${data.status}`);
// Include comet tokens in export
const responseWithTokens = await fetch('https://app.cometly.com/public-api/v1/contacts/exports', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
start_date: '2024-01-15 00:00:00',
end_date: '2024-01-15 23:59:59',
include_comet_tokens: true
})
});
// Include all emails in export
const responseWithEmails = await fetch('https://app.cometly.com/public-api/v1/contacts/exports', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
start_date: '2024-01-15 00:00:00',
end_date: '2024-01-15 23:59:59',
include_all_emails: true
})
});
const dataWithTokens = await responseWithTokens.json();
console.log(`Export created: ${dataWithTokens.export_id}, Status: ${dataWithTokens.status}`);
const dataWithEmails = await responseWithEmails.json();
console.log(`Export created: ${dataWithEmails.export_id}, Status: ${dataWithEmails.status}`);
<?php
$baseUrl = 'https://app.cometly.com/public-api/v1/contacts/exports';
$headers = [
'Authorization: Bearer YOUR_API_KEY',
'Accept: application/json',
'Content-Type: application/json'
];
// Basic export
$data = json_encode([
'start_date' => '2024-01-15 00:00:00',
'end_date' => '2024-01-15 23:59:59'
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);
echo "Export created: {$result['export_id']}, Status: {$result['status']}\n";
// Include comet tokens in export
$dataWithTokens = json_encode([
'start_date' => '2024-01-15 00:00:00',
'end_date' => '2024-01-15 23:59:59',
'include_comet_tokens' => true
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataWithTokens);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$responseWithTokens = curl_exec($ch);
$resultWithTokens = json_decode($responseWithTokens, true);
curl_close($ch);
echo "Export created: {$resultWithTokens['export_id']}, Status: {$resultWithTokens['status']}\n";
// Include all emails in export
$dataWithEmails = json_encode([
'start_date' => '2024-01-15 00:00:00',
'end_date' => '2024-01-15 23:59:59',
'include_all_emails' => true
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataWithEmails);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$responseWithEmails = curl_exec($ch);
$resultWithEmails = json_decode($responseWithEmails, true);
curl_close($ch);
echo "Export created: {$resultWithEmails['export_id']}, Status: {$resultWithEmails['status']}\n";
?>
import requests
base_url = 'https://app.cometly.com/public-api/v1/contacts/exports'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Accept': 'application/json',
'Content-Type': 'application/json'
}
# Basic export
data = {
'start_date': '2024-01-15 00:00:00',
'end_date': '2024-01-15 23:59:59'
}
response = requests.post(base_url, headers=headers, json=data)
result = response.json()
print(f"Export created: {result['export_id']}, Status: {result['status']}")
# Include comet tokens in export
data_with_tokens = {
'start_date': '2024-01-15 00:00:00',
'end_date': '2024-01-15 23:59:59',
'include_comet_tokens': True
}
response_with_tokens = requests.post(base_url, headers=headers, json=data_with_tokens)
result_with_tokens = response_with_tokens.json()
print(f"Export created: {result_with_tokens['export_id']}, Status: {result_with_tokens['status']}")
# Include all emails in export
data_with_emails = {
'start_date': '2024-01-15 00:00:00',
'end_date': '2024-01-15 23:59:59',
'include_all_emails': True
}
response_with_emails = requests.post(base_url, headers=headers, json=data_with_emails)
result_with_emails = response_with_emails.json()
print(f"Export created: {result_with_emails['export_id']}, Status: {result_with_emails['status']}")
Status Codes
| Status Code | Description |
|---|---|
| 202 | Export job created and queued for processing |
| 401 | Missing or invalid API key |
| 403 | API key doesn’t have permission or subscription is inactive |
| 422 | Invalid parameters provided (check error message for details) |
| 429 | Too 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_dateandend_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=1parameter to include the last 5 comet tokens for each contact in the export file. This parameter is optional and defaults to0. - All Emails: Use the
include_all_emails=1parameter to include all email addresses for each contact in the export file, including emails from merged profiles. This parameter is optional and defaults to0.