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

​
Overview

This endpoint creates an asynchronous export job that generates a downloadable file containing company 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 company data efficiently. For real-time needs, use the List Companies endpoint instead.
When to use exports: Exports are ideal for bulk data extraction (10,000+ companies). For smaller datasets, use the paginated list endpoint.

​
Request Body

​
Required Parameters

​
start_date
string
required
Start date and time for exporting companies in YYYY-MM-DD HH:MM:SS format. Exports companies 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 companies in YYYY-MM-DD HH:MM:SS format. Must be after start_date. Exports companies created until this timestamp in your space’s timezone.Example: 2024-01-15 23:59:59

​
Response

​
Success Response (202 Accepted)

​
export_id
integer
Unique identifier for the export job. Use this to check status with the Get Company 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 company record. 
{"id":123,"domain":"example.com","created_at":"2024-01-15T10:23:45Z"}
{"id":124,"domain":"acme.co","created_at":"2024-01-15T14:12:33Z"}
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/companies/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"
  }'

​
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 Company 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+ companies per export efficiently
  • Status Checking: Use the Get Company 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: Companies are filtered by created_at timestamp - only companies created within the specified date range are included