Create Export

POST/api/v1/exports

Create an export job from a search or a saved list. The job runs asynchronously — poll its status, then download the result. Creating an export charges credits for newly-exported companies.

Authentication#

Requires a token with the read_write scope, sent as Authorization: Bearer cornect_….

Request#

Body parameters:

Name	Type	Required	Description
`name`	string	Yes	A label for the export job.
`source_type`	string	No	Where rows come from: `search` (default) or `list`.
`search_filters`	object	No	For `source_type=search`: the same filter shape as Search Companies.
`sort_by`	string	No	Sort field for a search-sourced export.
`sort_order`	string	No	`asc` or `desc`.
`list_id`	string (UUID)	No	For `source_type=list`: the saved list to export.
`export_format`	string	No	`csv` (default) or `json`.

Response#

Returns the created job plus the credit math, so you can see exactly what was charged versus deduplicated for free.

json

{
  "export_job": {
    "id": "9f1c…",
    "name": "US fintech 50+",
    "status": "pending",
    "export_format": "csv",
    "source_type": "search"
  },
  "requested_count": 500,
  "already_unlocked": 320,
  "new_count": 180,
  "cost": 180,
  "credits_charged": 180,
  "capped_at_10k": false,
  "transaction_id": "…"
}

Credits#

You're charged 1 credit per newly-exported company. Companies already exported by your workspace are free (already_unlocked). A single export is capped at 10,000 companies.

All or nothing — a short balance is refused, not truncated

If your balance cannot cover cost in full, the call returns 402 insufficient_balance and nothing happens: no credits are charged, no job is created, no companies are unlocked. That applies to a balance of zero and to one that is merely short — they are the same condition.

The error carries the numbers you need to recover, so you do not have to call anything else to explain it:

json

{
  "detail": {
    "code": "insufficient_balance",
    "message": "This export needs 180 credits and the workspace has 40. Add 140 more credits, or narrow the filters, and try again. Nothing was charged.",
    "details": {
      "shortfall": 140,
      "cost": 180,
      "balance": 40,
      "matched_count": 500
    }
  }
}

Call Preview Export first — same body, no charge — and check would_skip, which is the shortfall. Above zero means this call will be refused. See also the Credit Consumption guide.

Code samples#

curl -X POST https://api.cornect.io/api/v1/exports \
  -H "Authorization: Bearer cornect_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"US fintech 50+","source_type":"search","export_format":"csv","search_filters":{"query":"fintech","countries":["United States"]}}'

Errors#

See Errors for the full table. Codes you're most likely to see here:

Code	Status	When
`insufficient_balance`	402	Balance is zero. A non-zero but insufficient balance does NOT 402 — it exports partially.
`INSUFFICIENT_SCOPE`	403	Token has read scope; this endpoint needs read_write.
`no_candidates`	400	No companies match the export criteria.
—	429	Rate limit exceeded (5/min).