Python SDK
TypeScript and Python are the maintained SDKs. The Go and Rust SDKs are unmaintained since 27 October 2026; use this SDK or the REST API.
pip install klozeoRequires Python 3.10+.
Quick start
Section titled “Quick start”from klozeo import ( Klozeo, Lead, text_attr, number_attr, city, rating, SortField, SortOrder, ExportFormat)
client = Klozeo("sk_live_your_api_key")
# Create a leadresp = client.create(Lead( name="Acme Corp", source="website", city="Berlin", attributes=[ text_attr("industry", "Software"), number_attr("employees", 500), ]))
# List with filtersresult = client.list( city().eq("Berlin"), rating().gte(4.0), sort_by=SortField.RATING, sort_order=SortOrder.DESC, limit=20,)
# Iterate all pages automaticallyfor lead in client.iterate(city().eq("Berlin")): print(lead.name)
# Export to CSVimport csv, iodata = client.export(ExportFormat.CSV)reader = csv.DictReader(io.StringIO(data.decode()))Handling errors
Section titled “Handling errors”from klozeo import KlozeoError, RateLimitedError, UnauthorizedError, NotFoundError
try: resp = client.create(Lead(name="Acme", source="web"))except RateLimitedError as e: print(f"Rate limited. Retry after {e.retry_after}s")except UnauthorizedError: print("Invalid or revoked API key")except NotFoundError: print("Lead not found")except KlozeoError as e: print(f"API error {e.status_code}: {e.message}")Safe retries
Section titled “Safe retries”A create can time out after Klozeo has saved it. Pass idempotency_key and retry the same request with the same API key while Klozeo retains the result. The retry writes nothing again. It works on create, batch_create and create_note, as a keyword argument. AsyncKlozeo takes it too.
resp = client.create( idempotency_key="import-42-row-7",)
client.batch_create(leads, idempotency_key="import-42")
client.create_note( lead_id, "Asked for a quote.", idempotency_key="import-42-row-7-note",)You choose the key. The SDK never makes one. A key is 1 to 200 printable ASCII characters. Use a new key for each new request. Klozeo keeps the result for 30 days. Using another API key, or retrying after the stored result is removed, starts a new request.
The SDK’s own retries on 429, 5xx, network errors and timeouts send the same key again.
A retry of a lead create returns the first result, even if the lead changed since. A retry of a note create returns the note as it is now. One key covers a whole batch. The SDK does not tell you whether a response is a replay.
A key problem is raised as a KlozeoError with a code:
idempotency_key_reused(409): the key was used with a different request. Nothing was written.idempotency_key_in_progress(409): the first request is still running. Wait a moment, then send the same request with the same key.NOTE_ALREADY_DELETED(410): the note was created, then deleted. No new note is written.invalid_idempotency_key(400): the key is empty, too long or has other characters. It is raised as aBadRequestError.
from klozeo import KlozeoError
try: client.create(lead, idempotency_key="import-42-row-7")except KlozeoError as e: if e.code == "idempotency_key_in_progress": pass # Wait a moment, then send the same request with the same key.Full source and examples: github.com/lbframe/klozeo-sdk-python
Package on PyPI: pypi.org/project/klozeo
Notes pagination
Section titled “Notes pagination”The existing notes list method returns all notes by following server cursors in
pages of 50. For bounded reads use list_notes_page(lead_id, limit=20, cursor=cursor) (also available on the async client).
The page includes notes, a continuation cursor and a has-more flag. Pass the cursor unchanged to read the next page. Iteration stops when
has_more is false. A missing or empty cursor while more notes remain, repeated
cursors and more than 10,000 pages raise an error
rather than returning a silently truncated history. API limits are 1–50 (default 20).
Lead history
Section titled “Lead history”client.list_changes(lead_id) returns a lead’s history as a list of LeadChange, newest first. It returns 50 entries by default and up to 100 with limit. limit goes from 1 to 100 (default 50). A higher value is capped at 100; a value below 1 uses 50. There is no cursor. actions keeps only the actions you name, as a list or as one name. The filter applies before limit, so frequent scored entries do not crowd out the others. AsyncKlozeo has the same method.
changes = client.list_changes( lead_id, limit=20, actions=["created", "updated", "merged"],)
for change in changes: print(change.action, change.created_at, change.api_key_id or change.actor_id)Each entry has an id, an action and a created_at (Unix time). actor_id is the member who made the change, when known. api_key_id is the API key behind a write made with a key, and it stays after the key is revoked. For such a write, actor_id is the account owner.
before and after hold snapshots with snake_case keys. Lead snapshots omit assignee and do_not_contact_by. Note snapshots omit author. A create has no before. A delete has no after. A scored entry holds only score. A note.created, note.updated or note.deleted entry holds the note. assigned and unassigned entries hold neither.
reason says why an entry exists, for example attribute:industry. assignee is the new assignee’s email on an assigned entry. channel says how the lead arrived, on created and merged entries: api, api_batch, mcp_classic, dashboard, import or save_leads. action and channel also accept a value that a later API version adds, so an older SDK keeps reading the history.
It works for a deleted lead. Klozeo keeps its history for 30 days. A daily job then erases before, after and assignee, so they are gone within 31 days of the deletion. The entries stay, with changed_fields, the names of the fields that changed. → List Lead Changes
Field locks
Section titled “Field locks”Lock a field you have verified so that duplicate merges, imports and company enrichment never overwrite it. Explicit updates (update, batch_update) still write it. Both calls are idempotent, need the editor or owner role, and return the lead. AsyncKlozeo has the same methods.
lead = client.lock_field("cl_01234567-...", "city")lead.locked_fields # ["city"]
resp = client.create(Lead(name="Acme Corporation", source="import", email="[email protected]", city="Nice"))resp.skipped_locked_fields # ["city"]: the merge kept the stored city
client.unlock_field("cl_01234567-...", "city")See Field locks. Lockable fields: source, description, address, city, state, country, postal_code, phone, email, website, rating, review_count, category, tags, source_id, siren, logo_url. Batch create items carry skipped_locked_fields too. locked_fields is read-only: create never sends it.
Attribute locks
Section titled “Attribute locks”Lock a custom attribute with lock_attribute(lead_id, attr_id) and unlock it with unlock_attribute(lead_id, attr_id). Take the attribute ID from list_attributes or from attributes in get. Duplicate merges, imports and company enrichment then never write it, and a merge that sends it lists it in attribute_changes as ignored, with the reason locked. update_attribute still writes it, and it stays locked. Both calls are idempotent, need an API key with the full scope, and return the attribute. AsyncKlozeo has the same methods.
In this example the lead has a valid email and an existing industry attribute. The create sends that same email, so it merges into the lead, and the locked industry is ignored.
lead_id = "cl_01234567-..."lead = client.get(lead_id)lead.email # "[email protected]"industry = next(a for a in lead.attributes if a.name == "industry")
attr = client.lock_attribute(lead_id, industry.id)attr.locked # True
resp = client.create(Lead(name=lead.name, source="import", email=lead.email, attributes=[text_attr("industry", "Retail")]))resp.duplicate # True[(c.name, c.action, c.reason) for c in resp.attribute_changes] # [("industry", "ignored", "locked")]
client.unlock_attribute(lead_id, industry.id)See Lock Attribute. locked is True only on a locked attribute, also in list_attributes and get. It is read-only: create_attribute never sends it. Batch create items carry attribute_changes too.
Lock policy
Section titled “Lock policy”The workspace lock policy lists the fields and custom attributes to freeze after their first value, on leads created after each name takes effect. get_lock_policy() returns a LockPolicy with two lists, fields and attributes. Each LockPolicyEntry has a name and effective_at, the time the name took effect, in Unix seconds. A full or read API key can read it.
replace_lock_policy(fields, attributes) replaces the whole policy and returns the new one. Send both lists, even when one does not change, and [] to empty one. To add a name, send the current names with it. Only the owner and admins can replace the policy, and only the owner on the Free plan; from the SDK, that takes an API key with the full scope. AsyncKlozeo has the same methods.
from klozeo import KlozeoError
policy = client.get_lock_policy()[(e.name, e.effective_at) for e in policy.attributes] # [("utm_campaign", 1794925800)]
try: updated = client.replace_lock_policy( fields=[e.name for e in policy.fields], attributes=[*(e.name for e in policy.attributes), "utm_source"], ) [e.name for e in updated.attributes] # ["utm_campaign", "utm_source"]: utm_campaign keeps its effective_atexcept KlozeoError as e: if e.code == "save_temporarily_unavailable": pass # Nothing was saved. Try the replace again later. else: raisefields takes the lockable fields listed above. attributes takes exact custom attribute names, case-sensitive, 1 to 255 characters each, at most 50. A name sent twice is stored once. A broken rule raises a BadRequestError and nothing is saved. A name already in the policy keeps its effective_at; a new name covers only leads created from then on. The policy never locks existing leads, and removing a name leaves the locks already set.
If the policy cannot be saved right now, the SDK retries on its own, like any 5xx, then raises a KlozeoError with status_code 503 and code save_temporarily_unavailable. Nothing is saved.
See Lock policy. The AccountExport type describes the document export_account() returns, with lock_policy and statuses optional; export_account() still returns raw bytes.