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.
Endpoint
Section titled “Endpoint”GET /leads/exportParameters
Section titled “Parameters”format defaults to json. See the generated reference for all parameters.
Examples
Section titled “Examples”# Export all leads as CSVcurl -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 descendingcurl -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"Response
Section titled “Response”| 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.
Notes and custom attributes
Section titled “Notes and custom attributes”- JSON: each lead carries its
attributes(name, type, value, and"locked": trueon a locked attribute) andnotes(oldest first). - CSV and XLSX: the
notescolumn 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 theassigneecolumn comes oneattr:<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,
numberandboolattributes 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.
Endpoint reference
Section titled “Endpoint reference”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 |
GET /api/v1/leads/export
Section titled “GET /api/v1/leads/export”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:
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. |
Schemas and errors
Section titled “Schemas and errors”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.
Attribute
Section titled “Attribute”{"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."} |
Error400
Section titled “Error400”{"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}]}
Error401
Section titled “Error401”{"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}]}
Error403
Section titled “Error403”{"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}]}
Error413
Section titled “Error413”{"oneOf":[{"type":"object","properties":{"error":{"const":"payload_too_large"},"code":{"const":"payload_too_large"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error429
Section titled “Error429”{"oneOf":[{"type":"object","properties":{"error":{"const":"rate_limit_exceeded"},"code":{"const":"rate_limit_exceeded"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error500
Section titled “Error500”{"oneOf":[{"type":"object","properties":{"error":{"const":"internal_error"},"code":{"const":"internal_error"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error503
Section titled “Error503”{"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."} |
Warning
Section titled “Warning”{"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."} |