Skip to content

Export Leads: CSV, JSON, XLSX

Export all leads (or a filtered subset) to CSV, JSON, or XLSX. Unlike the List endpoint, export returns all matching records in a single response (no pagination, no cursor). Use this for data backups, bulk processing, or feeding external tools.

CSV cells beginning with =, +, -, @, tab (\t), carriage return (\r) or line feed (\n) receive a leading apostrophe (') to prevent spreadsheet formula execution. JSON and XLSX exports preserve their existing representation.

GET /leads/export

format defaults to json. See the generated reference for all parameters.

Terminal window
# Export all leads as CSV
curl -o leads.csv \
"https://api.klozeo.com/api/v1/leads/export?format=csv" \
-H "X-API-Key: sk_live_your_key"
# Export Paris leads with rating ≥ 4, sorted by rating descending
curl -o leads.xlsx \
"https://api.klozeo.com/api/v1/leads/export?format=xlsx&filter=and.eq.city.Paris&filter=and.gte.rating.4&sort_by=rating&sort_order=DESC" \
-H "X-API-Key: sk_live_your_key"
Format Content-Type Notes
csv text/csv UTF-8 encoded, comma-separated
json application/json Array of full lead objects
xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Excel-compatible

CSV and XLSX share one column order. New fixed columns are only ever added after the existing fixed columns, before the attribute columns. Read attribute columns by their header, not their position: they are sorted by name, so they shift when an attribute name or a fixed column is added. After do_not_contact, do_not_contact_at, siren and locked_fields come your notes, the assignee and your custom attributes; tags and locked_fields join their values with |. Every format carries each lead’s assignee, the email of the person it is assigned to; in CSV and XLSX, the cell is empty when nobody is.

  • JSON: each lead carries its attributes (name, type, value, and "locked": true on a locked attribute) and notes (oldest first).
  • CSV and XLSX: the notes column holds every note of the lead in one cell, oldest first, one note per line, each starting with its date ([2026-11-04] Called, call back Monday). After the assignee column comes one attr:<name> column per custom attribute name used in your account, sorted by name. The columns are the same whatever your filters, so a filtered export lines up with a full one. A lead without that attribute has an empty cell.
  • In XLSX, number and bool attributes are real numbers and booleans, ready for formulas. Lists and objects appear as JSON text.
  • Up to 200 attribute columns. If your account uses more attribute names, the attributes past the 200th name (in sorted order) are grouped in a last column named attributes_overflow, as one JSON object per lead. Nothing is left out.
  • An XLSX cell holds at most 32,767 characters, so a longer text is cut there. The JSON export always has the full text.

Large exports are streamed, so they start downloading right away. If an export fails after it has started, the download is interrupted rather than ending in a file that looks complete: run it again.

Paths include the /api/v1 prefix. Schema fields marked required must be present; other fields may be omitted. Nullable values are shown explicitly.

Method Path Description
GET /api/v1/leads/export Export leads

JSON nests each lead’s attributes and notes. CSV and XLSX keep their columns in order and append notes (every note in one cell, oldest first, each line prefixed by its UTC date), then assignee (the assignee’s email, empty when unassigned), then one attr: column per attribute name used in the account, sorted by name. Past 200 names, the remaining attributes share a final attributes_overflow column as one JSON object. XLSX number and bool attributes are typed cells. The response is streamed: a failure after the first 64 KiB breaks the transfer instead of returning a status.

Accepted authentication: ApiKey or BearerKey.

Parameter In Required Schema Description
sort_by query no {"type":"string"} Sort field; unknown values fall back to created_at. status sorts by the workspace’s status list order, values the list does not name after the listed ones in ascending order, by value.
sort_order query no {"type":"string"} ASC or DESC, case-insensitive; default DESC. Any other value sorts DESC, and an unknown sort_by exports newest first.
filter query no {"type":"array","items":{"type":"string"}} Repeated logic.operator.field.value expressions; logic is and or or. attr:name addresses typed custom attributes. assignee takes eq, neq or in with an email or me (the caller; the workspace owner for an API key), or is_empty and is_not_empty. neq also returns unassigned leads. Malformed expressions, unsupported operators/fields and invalid numeric values return 400.
format query no {"type":"string","enum":["json","csv","xlsx"]} Default json.
Status Description Content type / schema Headers
200 Success application/json: {"type":["array","null"],"items":{"$ref":"#/components/schemas/Lead"}}; text/csv: {"type":"string"}; application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: {"type":"string","format":"binary"} X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.
400 Request rejected. application/json: Error400 X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.
401 Invalid or missing credentials. application/json: Error401 X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.
403 Permission denied. Create lead also returns leads_limit_reached when the storage quota is reached. lead_access_required: an admin without lead access from the workspace owner, on the dashboard or an assistant connection. That admin can still manage API keys, webhooks, scoring rules and the lock policy. API keys never get it. workspace_read_only: the workspace is read-only because its owner owns another Free workspace ranked before it (their first workspace, otherwise the oldest), and only one Free workspace per owner stays editable. Editing resumes when this workspace moves to Pro or Scale, or when its owner no longer owns any Free workspace ranked before it. Every change to leads, scoring rules, the status list and the lock policy is refused, from an API key, the dashboard or an assistant connection. Reading, export, members, API keys, webhooks and assistant connections still work. application/json: Error403 X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; WWW-Authenticate: {"type":"string"} Present for MCP insufficient_scope.
413 Body exceeds 1 MiB (10 MiB for /leads/batch). application/json: Error413 X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.
429 Rate limit exceeded. Retry-After is always present. Quota exhaustion (computed or cached) includes all four X-RateLimit-* headers. The earlier per-key admission-work refusal can omit those quota headers. application/json: Error429 X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; Retry-After: {"type":"integer"} Seconds until retry. Early admission refusals may omit the quota headers.
500 Internal error. application/json: Error500 X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.
503 Authentication unavailable. application/json: Error503 X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.

Schema names in the endpoint tables refer to the definitions below. oneOf means exactly one alternative; anyOf means at least one. Error alternatives list the exact error and code values.

{"type":"object","additionalProperties":false}

Field Required Schema
id no {"type":"string"}
name yes {"type":"string"}
type yes {"type":"string"}
value yes {}
locked no {"type":"boolean","description":"true when the attribute is locked: duplicate merges, imports, inbound sources and company enrichment never write it. Omitted when the attribute is not locked. Returned by GET /leads/{id}, GET /leads/{id}/attributes, POST /leads/{id}/attributes, the lock operations and JSON exports. Sending it in a request does not lock the attribute: use POST /leads/{id}/attributes/{attr_id}/lock."}

{"oneOf":[{"type":"object","properties":{"error":{"const":"bad_request"},"code":{"const":"bad_request"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"invalid_scoring_expression"},"code":{"const":"invalid_scoring_expression"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"scoring_rules_limit_reached"},"code":{"const":"scoring_rules_limit_reached"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"assignee_not_member"},"code":{"const":"assignee_not_member"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}

{"oneOf":[{"type":"object","properties":{"error":{"const":"unauthorized"},"code":{"const":"unauthorized"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"invalid_token"},"code":{"const":"invalid_token"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}

{"oneOf":[{"type":"object","properties":{"error":{"const":"forbidden"},"code":{"const":"forbidden"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"insufficient_scope"},"code":{"const":"insufficient_scope"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"leads_limit_reached"},"code":{"const":"leads_limit_reached"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"lead_access_required"},"code":{"const":"lead_access_required"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"workspace_read_only"},"code":{"const":"workspace_read_only"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}

{"oneOf":[{"type":"object","properties":{"error":{"const":"payload_too_large"},"code":{"const":"payload_too_large"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}

{"oneOf":[{"type":"object","properties":{"error":{"const":"rate_limit_exceeded"},"code":{"const":"rate_limit_exceeded"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}

{"oneOf":[{"type":"object","properties":{"error":{"const":"internal_error"},"code":{"const":"internal_error"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}

{"oneOf":[{"type":"object","properties":{"error":{"const":"internal_error"},"code":{"const":"internal_error"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}

{"type":"object","additionalProperties":false}

Field Required Schema
id yes {"type":"string"}
name yes {"type":"string"}
source yes {"type":"string"}
description no {"type":"string"}
address no {"type":"string"}
city no {"type":"string"}
state no {"type":"string"}
country no {"type":"string"}
postal_code no {"type":"string"}
latitude no {"type":"number"}
longitude no {"type":"number"}
phone no {"type":"string"}
email no {"type":"string"}
website no {"type":"string"}
rating no {"type":"number"}
review_count no {"type":"integer"}
category no {"type":"string"}
tags no {"type":["array","null"],"items":{"type":"string"}}
source_id no {"type":"string"}
siren no {"type":"string"}
logo_url no {"type":"string"}
status no {"type":"string","description":"The lead's status value, up to 50 characters. Exports and webhooks carry this value, not the dashboard label."}
assignee no {"type":["string","null"],"description":"Email of the workspace owner or a member the lead is assigned to, or null."}
attributes no {"type":["array","null"],"items":{"$ref":"#/components/schemas/Attribute"}}
notes no {"type":["array","null"],"items":{"$ref":"#/components/schemas/Note"}}
score no {"type":"number"}
created_at no {"type":"integer"}
updated_at no {"type":"integer"}
last_interaction_at no {"type":"integer"}
do_not_contact yes {"type":"boolean"}
do_not_contact_at no {"type":"integer"}
do_not_contact_origin no {"type":"string"}
do_not_contact_by no {"type":"string"}
locked_fields yes {"type":["array","null"],"items":{"type":"string"}}
warnings no {"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Only in the response of PUT /leads/{id}: values the update left out, by field and code; the value is never echoed. invalid_email: the email was invalid, so the stored email was kept. Absent when there are none."}

{"type":"object","additionalProperties":false}

Field Required Schema
id yes {"type":"string"}
lead_id yes {"type":"string"}
content yes {"type":"string"}
created_at yes {"type":"integer"}
updated_at yes {"type":"integer"}
author no {"type":["string","null"],"description":"Email of the person who wrote the note: the member who wrote it in the dashboard or through an assistant, or the workspace owner for a note written with an API key. null when that person's account has been deleted, and for some notes written before November 2026. Editing a note does not change it."}
api_key_id no {"type":["string","null"],"description":"The API key the note was written with, through the REST API or the MCP server with a key. Editing a note does not change it. The id stays after the key is revoked."}

{"type":"object","description":"A value a write accepted the lead without, named by field and code, never by value.","additionalProperties":false}

Field Required Schema
field yes {"type":"string","description":"The request field, for example email."}
code yes {"type":"string","description":"invalid_email: the email was invalid and not stored. New codes may be added."}