> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Contact Export
> Create an asynchronous export job to generate a downloadable file of contacts
## 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](/api-reference/endpoint/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 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 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
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`.
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)
Unique identifier for the export job. Use this to check status with the [Get Contact Export](/api-reference/endpoint/get-contact-export) endpoint.
Current status of the export. Will be `queued` immediately after creation.
### Error Response
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.
```json theme={null}
{"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:
```json theme={null}
{"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:
```json theme={null}
{"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
```bash cURL theme={null}
# 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
}'
```
```javascript JavaScript theme={null}
// 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 PHP theme={null}
'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";
?>
```
```python Python theme={null}
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](/introduction/rate-limiting) |
## Next Steps
After creating an export, poll the [Get Contact Export](/api-reference/endpoint/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](/introduction/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](/api-reference/endpoint/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`.