Export a list

Exports are asynchronous: start a job, poll it, download the file. A synchronous endpoint would have to build and stream an arbitrarily large CSV inside a single request window; a job keeps working for as long as the export takes, and each poll is a light request against your rate limits. Both endpoints require a key with the lists scope — see Scopes.

Start the export

POST /business/lists/{listId}/export with an empty JSON body:

curl -X POST "https://api.tryfuse.ai/api/v1/business/lists/665f1c2ab61e0a3d90b1e777/export" \
  -u "af_YOUR_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'

The API responds 202 with a job id:

{
  "jobId": "68a1f5209c41d20014b3eb11"
}

A 202 means accepted, not finished — the file does not exist yet. Hold on to jobId; it is your only handle on the export. If the list does not exist, or belongs to a different workspace, you get 404 with the standard error envelope:

{
  "error": {
    "code": "LIST_NOT_FOUND",
    "message": "The requested list was not found.",
    "param": null,
    "doc_url": "https://fuseai.com/api/errors/list_not_found",
    "request_id": "req_8fK2mQ4x"
  }
}

Poll the job

GET /business/exports/{jobId} returns the job’s current state:

curl "https://api.tryfuse.ai/api/v1/business/exports/68a1f5209c41d20014b3eb11" \
  -u "af_YOUR_KEY:"

{
  "exportJob": {
    "jobId": "68a1f5209c41d20014b3eb11",
    "status": "completed",
    "rowCount": 412,
    "downloadUrl": "https://fuseai-csv-uploads.s3.amazonaws.com/exports/.../export.csv?X-Amz-Signature=...",
    "error": null
  }
}

status moves through a fixed lifecycle:

Status	Meaning
`pending`	Accepted, waiting to be picked up
`processing`	The CSV is being built
`completed`	Done — `downloadUrl` and `rowCount` are set
`failed`	Terminal — `error` explains why when a specific reason is known

completed and failed are terminal; once you see either, stop polling. Poll every few seconds with backoff — typical exports complete in seconds to a couple of minutes depending on list size. A compact loop:

import time
import requests

BASE = "https://api.tryfuse.ai/api/v1"
AUTH = ("af_YOUR_KEY", "")

job_id = requests.post(
    f"{BASE}/business/lists/{list_id}/export", auth=AUTH, json={}
).json()["jobId"]

delay = 2
while True:
    job = requests.get(
        f"{BASE}/business/exports/{job_id}", auth=AUTH
    ).json()["exportJob"]
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 15)

if job["status"] == "completed":
    # The URL is presigned — no Authorization header on this request.
    csv_bytes = requests.get(job["downloadUrl"]).content
else:
    raise RuntimeError(f"Export failed: {job['error']}")

Polling an unknown jobId — or one that has since expired — returns 404 EXPORT_NOT_FOUND. There is nothing to recover from that job; start a new export instead.

Download the file

downloadUrl is a presigned URL: fetch it directly, with no authentication header. It is valid for roughly 15 minutes — presigned URLs are short-lived on purpose, so a leaked link does not become a permanent public copy of your data. Every poll of a completed job returns a freshly signed URL, so if yours expires before you download, poll once more and use the new one. The file downloads named after the list. rowCount is the number of data rows — the header row is not counted. Each row carries the contact’s identity fields, emails and phones, company fields, and your custom columns. It also includes a Fuse Contact ID column: keep it intact if you plan to edit the file offline and bring it back, because a re-upload uses it to match rows to existing contacts instead of creating duplicates — see Upload your contacts.

When exports fail

A failed job sets error to a specific reason when there is one:

`error`	Meaning	What to do
`EMPTY_LIST`	The list has no members	Add members first — see Build a list from search
`NO_DATA`	The list has members, but none produced exportable data	Enrich or populate the list before exporting again
`LIST_NOT_FOUND`	The list could not be found when the job ran	Verify the list still exists
`EXPORT_FAILED`	A transient failure with no more specific cause	Retry by starting a new export

Failed jobs are terminal. Retrying means calling POST /business/lists/{listId}/export again for a fresh jobId — re-polling a failed job will only ever return failed.

Get started

Concepts

Guides

Start the export

Poll the job

Download the file

When exports fail

Next steps

Upload your contacts

API reference

​Start the export

​Poll the job

​Download the file

​When exports fail

​Next steps

Upload your contacts

API reference

Start the export

Poll the job

Download the file

When exports fail

Next steps