Leads
Base URL: https://api.klozeo.com/api/v1
Auth: Use X-API-Key: sk_live_... or Authorization: Bearer sk_live_..., never both.
ID format
Section titled “ID format”Lead IDs use the prefix cl_ (e.g., cl_01234567-89ab-cdef-0123-456789abcdef). Always include the full ID with the prefix in API requests.
Lead object
Section titled “Lead object”See the generated reference below.
All timestamps are Unix seconds (not milliseconds). For JavaScript: new Date(timestamp * 1000).
List Leads
Section titled “List Leads”GET /leadsSee the generated reference below.
Response 200 OK:
{ "leads": [{ "id": "cl_...", "name": "Acme", "source": "website", "score": 87, "do_not_contact": false, "locked_fields": [] }], "next_cursor": "eyJpZCI6ImNsXzAxMjM...", "has_more": true, "count": 50}Create Lead
Section titled “Create Lead”POST /leadsRequired fields: name, source. All other fields are optional. Surrounding spaces in name are removed; a name with nothing else returns 400 with the message name is required (batch: per-item error).
status accepts any value up to 50 characters and is stored as sent; a lead created without one is new. Each workspace has its own status list; new, contacted, qualified, disqualified and converted are the defaults. A longer status returns 400 (batch: per-item error), on create and on update. Tags are stored exactly as sent, including commas, quotes, braces and backslashes.
assignee takes the email of the workspace owner or of an active member, whatever their role. The email is matched without regard to case, and the lead returns it as assignee, or null when nobody is assigned. Any other email returns 400 with the code assignee_not_member (batch: a per-item error with that message), on create and on update.
email is stored without surrounding spaces and in lowercase; from Jean Dupont <[email protected]> only [email protected] is kept. An invalid email (not one address with one @, a domain with a dot and no empty part, no space, at most 254 characters) never fails the request: the lead is written without it, it never matches a duplicate, and the response carries "warnings": [{ "field": "email", "code": "invalid_email" }], without the value. The lead’s history keeps the value received. The same rule applies to updates and batches. → Valid emails
{ "name": "Acme Corporation", "source": "website", "city": "San Francisco", "rating": 4.5, "tags": ["enterprise"], "attributes": [ { "name": "industry", "type": "text", "value": "Software" }, { "name": "employees", "type": "number", "value": 500 } ]}Automatic deduplication runs before every insert. The response varies depending on the outcome:
// New lead created (201 Created){ "id": "cl_...", "message": "Lead created successfully", "created_at": 1703520000 }
// Duplicate detected and merged (200 OK){ "id": "cl_existing...", "message": "Duplicate detected, existing lead updated", "created_at": 1703520000, "duplicate": true, "attribute_changes": [{ "name": "industry", "action": "updated" }, { "name": "employees", "action": "ignored", "reason": "type_mismatch" }], "skipped_locked_fields": ["city"] }
// Low-confidence match — new lead created with a hint (201 Created){ "id": "cl_new...", "message": "Lead created successfully", "potential_duplicate_id": "cl_similar..." }
// Invalid email: lead created without it (201 Created){ "id": "cl_new...", "message": "Lead created successfully", "warnings": [{ "field": "email", "code": "invalid_email" }] }Deduplication priority:
| Priority | Criterion | Confidence | Action |
|---|---|---|---|
| 1 | valid email match (case-insensitive) |
High | Merge → 200 + "duplicate": true |
| 2 | siren match |
High | Merge → 200 + "duplicate": true |
| 3 | source_id match (exact) |
High | Merge → 200 + "duplicate": true |
| 4 | phone + name similarity > 80% |
Medium | Merge → 200 + "duplicate": true |
| 5 | name + city match |
Low | Create + "potential_duplicate_id" |
On a merge, non-empty incoming fields overwrite existing ones. A merge never writes name, status, assignee (an unknown assignee still returns 400), latitude, longitude or locked fields; incoming locked fields are listed in skipped_locked_fields. last_interaction_at is always bumped.
Custom attributes merge by exact name: a new name is added, an existing name with the same type takes the incoming value, and attributes you do not send stay unchanged. A locked attribute is never written. attribute_changes reports each incoming attribute in request order as added, updated or ignored with a reason (locked when the attribute is locked, type_mismatch when the stored type differs, ambiguous_name when several stored attributes share the name). It is omitted when no attribute is sent. An invalid attribute refuses the whole merge. → Deduplication
Error 403 (leads_limit_reached) when the account’s lead limit is reached (Free: 2,500 leads).
Error 409 Conflict when a unique-index violation on email or source_id cannot be resolved by merge (rare race after INSERT):
{ "error": "conflict", "message": "A lead with this email or source_id already exists", "code": "conflict" }Get Lead
Section titled “Get Lead”GET /leads/{id}Response 200 OK: Full lead object (see schema above).
Error 404 if the lead does not exist or belongs to a different account.
Update Lead
Section titled “Update Lead”PUT /leads/{id}Partial update: only include fields to change. Returns the updated lead. A name is stored without surrounding spaces; an empty or blank name returns 400 with the message name is required (batch: per-item error) and leaves the lead unchanged.
"assignee": null or "assignee": "" removes the assignee. A member who leaves the workspace stays assigned to their leads until you change them, and cannot be assigned again.
An email is stored as on create. An invalid one is left out of the update, so the lead keeps the email it had; the other fields are still updated and the returned lead carries "warnings": [{ "field": "email", "code": "invalid_email" }]. "email": "" still removes the email.
{ "rating": 4.8, "city": "New York", "tags": ["enterprise", "updated"] }Error 404 if the lead does not exist or belongs to a different account.
Error 409 Conflict if the update would set an email or source_id already owned by another lead:
{ "error": "conflict", "message": "A lead with this email or source_id already exists", "code": "conflict" }Delete Lead
Section titled “Delete Lead”DELETE /leads/{id}Response 204 No Content.
Error 404 if the lead does not exist or belongs to a different account.
Field locks
Section titled “Field locks”POST /leads/{id}/locks/{field}DELETE /leads/{id}/locks/{field}Lock a field you have verified: duplicate merges and imports (POST /leads, POST /leads/batch, MCP create_lead / batch_create_leads) and company enrichment never overwrite it. Lockable fields: source, description, address, city, state, country, postal_code, phone, email, website, rating, review_count, category, tags, source_id, siren, logo_url. A locked tags field receives no new tag on merge. To lock a custom attribute, see Lock Attribute.
A lock protects against automatic writes, not against you: PUT /leads/{id}, PUT /leads/batch and MCP update_lead still write a locked field. A person’s edit in the dashboard also locks the fields it changes.
Editor or owner. Both calls are idempotent and return 200 with the lead. Each actual change is recorded in the audit trail with reason field_lock:locked:<field> or field_lock:unlocked:<field> and the acting user, and fires the lead.updated webhook. Exports add a locked_fields column (field names joined with |).
field_lock:policy:<field> and attribute_lock:policy:<name>: the lock was set by the workspace lock policy.
A merge that skipped locked fields lists them:
{ "id": "cl_existing...", "message": "Duplicate detected, existing lead updated", "created_at": 1703520000, "duplicate": true, "skipped_locked_fields": ["city"] }In a batch, each merged item of created carries its own skipped_locked_fields.
Error 400 for a field that cannot be locked. Error 404 if the lead does not exist or belongs to a different account.
Lock policy
Section titled “Lock policy”GET /lock-policyPUT /lock-policyThe workspace lock policy lists the fields and custom attributes to freeze after their first value. Every member can read it; only the owner and admins can replace it. Each name takes effect from the moment it is added: only leads created from then on are locked, never existing ones. → How the policy locks leads
GET /lock-policy returns two lists, fields and attributes. Each entry has a name and effective_at, the time the name took effect, in Unix seconds. Each list is sorted by name in byte order, so UTM_Source comes before utm_source. A workspace without a policy gets two empty lists. Every member can read the policy, and so can any API key that can read leads.
Response 200 OK:
{ "fields": [ { "name": "siren", "effective_at": 1793610000 }, { "name": "source", "effective_at": 1793610000 } ], "attributes": [ { "name": "utm_campaign", "effective_at": 1794925800 } ]}PUT /lock-policy replaces the whole policy with the names you send. Send both lists, even when one does not change: a request without fields or attributes is refused, so a list is never cleared by accident. Send [] to empty a list.
{ "fields": ["source", "siren"], "attributes": ["utm_campaign", "utm_source"] }Rules:
fieldsholds lockable fields only, written exactly as listed there.attributesholds exact custom attribute names, case-sensitive:UTM_Sourceandutm_sourceare two names. Each name has 1 to 255 characters, and the list holds at most 50 names.- A name sent twice is stored once.
- A name already in the policy keeps its
effective_at. A new name, or a name you removed and add again, takes effect when the replace is applied: leads created before then are not locked for it.
Only the workspace owner and its admins can replace the policy; on the Free plan, only the owner. An API key needs the full scope and acts as the owner. An admin without lead access can still read and replace it, as for scoring rules. Replacing the policy fires no webhook and changes no lead by itself.
Response 200 OK: the new policy, as GET /lock-policy returns it.
Error 400 (bad_request) when the body is not valid JSON, a list is missing, a field cannot be locked (the message lists the lockable fields), an attribute name is empty or longer than 255 characters, or there are more than 50 attribute names. Nothing is saved.
Error 403 for a write API key or an assistant connection, on both calls. On PUT, also for a viewer, an editor or a read API key, and workspace_read_only in a read-only workspace.
Error 503 (save_temporarily_unavailable) when the policy cannot be saved right now. Nothing is saved: retry after the Retry-After delay.
List Lead Changes
Section titled “List Lead Changes”GET /leads/{id}/changes?limit=50Audit trail for a lead (newest first). Default limit 50, max 100. action keeps only the listed actions, comma-separated, before the limit: ?action=created,updated,merged leaves out score changes. See Deduplication → Audit trail.
{ "changes": [ { "id": "uuid-...", "lead_id": "cl_...", "workspace_id": "...", "user_id": "...", "actor_id": "...", "api_key_id": "...", "action": "merged", "before": {}, "after": {}, "reason": "dedup:email", "created_at": 1703520000 } ], "count": 1}action is one of created, updated, merged, deleted, scored, assigned, unassigned, note.created, note.updated, note.deleted. An assigned entry carries the new assignee’s email in assignee; an unassigned entry records that the assignee was removed. A scored entry records a score change: before and after hold only score. A custom attribute added, changed or removed is an updated entry with reason attribute:<name>. Locking or unlocking a custom attribute is an updated entry with reason attribute_lock:locked:<name> or attribute_lock:unlocked:<name>. A note.* entry holds the note in before and after. Deleting a lead writes one note.deleted entry per note, with reason lead:deleted. api_key_id is the id of the API key behind a change made with a key, and stays after the key is revoked. For such a change actor_id is the account owner. The entries a create or a duplicate merge recorded carry channel, how the lead arrived: api (POST /leads with an API key), api_batch (POST /leads/batch with an API key), mcp_classic (MCP with an API key), dashboard, import (dashboard import, CSV or JSON) or save_leads (an AI assistant connected with OAuth). Klozeo sets it from your credential and the route; no request field sets it. Older entries have none. Within 31 days of a lead’s deletion, its entries are erased: they carry changed_fields, the names of the fields that changed, and no before, after or assignee. See Audit trail.
Batch Create
Section titled “Batch Create”POST /leads/batchUp to 100 leads (Free) or 500 leads (Pro) per request. Exceeding the limit returns 400 Bad Request: the entire request is rejected and no leads are created. An empty leads array also returns 400.
Deduplication runs per item (same logic as POST /leads). Merges count as success with duplicate: true and do not consume a leads slot. A merged item that sent attributes carries its own attribute_changes. An item whose email was invalid is saved without it and carries its own warnings.
{ "leads": [ { "name": "Lead 1", "source": "import", "city": "Athens" }, { "name": "Lead 2", "source": "import", "city": "London" } ]}Response 201 Created (all succeeded) or 207 Multi-Status (partial failure):
207 Multi-Statusmeans at least one lead failed. Always check theerrorsarray, even when the request returned 207 and not a 4xx/5xx. Entries increatedwere saved successfully.
{ "created": [{ "index": 0, "id": "cl_...", "created_at": 1703520000 }], "errors": [{ "index": 1, "message": "name is required" }], "total": 2, "success": 1, "failed": 1}Batch Update
Section titled “Batch Update”PUT /leads/batchApply the same partial update to multiple leads. 200 OK if all succeed, 207 Multi-Status if any fail; walk results[]. Empty ids → 400. When data.email is invalid, it is left out for every lead and the response carries one top-level warnings array, as for PUT /leads/{id}.
{ "ids": ["cl_aaa...", "cl_bbb..."], "data": { "source": "LinkedIn" }}Batch Delete
Section titled “Batch Delete”DELETE /leads/batchSame status rules as batch update (200 / 207 + results[]). Empty ids → 400.
{ "ids": ["cl_aaa...", "cl_bbb..."] }Batch update/delete results
Section titled “Batch update/delete results”For batch update and delete, inspect results[]: only affected leads have success: true. Missing IDs and IDs outside your account both return success: false, message: "not found". The existing HTTP 207 status applies whenever any item fails (including all items). Grouped webhooks include only successful IDs and their actual count; no event is emitted when all items fail.
Recalculate Score
Section titled “Recalculate Score”POST /leads/{id}/scoreRecalculates and persists the score for a single lead based on current scoring rules.
Bulk Recalculate Scores
Section titled “Bulk Recalculate Scores”POST /leads/score/batchRecalculates scores for all leads in your account.
Export
Section titled “Export”GET /leads/export?format=csvSee the Export reference for full details.
Common errors
Section titled “Common errors”See the generated reference below.
SIREN is returned on lead reads and exports and supports text filters, e.g. filter=and.eq.siren.732829320. Invalid SIREN/SIRET returns HTTP 400 (batch: per-item error). A conflicting SIREN on update returns HTTP 409. SIRET is accepted in siren; the establishment suffix is not stored.
SIREN/SIRET input must contain only ASCII digits: spaces (including surrounding
spaces), dots and other separators are rejected with 400. SIRETs for La Poste
(SIREN 356000000) use a digit sum divisible by 5; other identifiers use Luhn,
including the 9-digit SIREN prefix of a SIRET.
For sole proprietors, a SIREN can identify a natural person. Klozeo stores only the canonical 9-digit SIREN to identify and deduplicate leads. It is included in lead reads, exports and configured webhooks; the SIRET establishment suffix is not stored or sent in those webhooks.
Optional French company enrichment
Section titled “Optional French company enrichment”POST /leads/{id}/enrich explicitly looks up the stored SIREN. Returns
{ "lead": { ... }, "enriched": true|false }; 404 for an inaccessible lead,
403 for a viewer. No SIREN, no match, timeout, upstream failure or rate admission
returns the existing lead with enriched: false (200). No external lookup is made
by default. enrich: true on a create item (single or batch) requests best-effort
enrichment after creation/merge; any enrichment error leaves the create successful.
Only empty address, city, postal_code and text attributes official_name,
naf_code, headcount_range are filled. The headcount value is the INSEE range
code; the legal name is preferred to the API’s constructed complete name. Existing
values and types are preserved. The write and actor audit are atomic; SIREN is
rechecked at write time. Responses include the attributes after enrichment.
Provider: API Recherche d’entreprises.
Only the SIREN is sent; fixed HTTPS host, 800 ms timeout, no redirects or retry,
1 request/second/process, cache 256 companies for 1 hour; rate-limited requests
skip enrichment. A batch may therefore enrich only some companies. Retry later
with the explicit endpoint. Classic MCP exposes enrich_lead and optional
enrich on create tools; these additions are unavailable on the OAuth catalog.
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 |
List leads |
| POST | /api/v1/leads |
Create lead |
| POST | /api/v1/leads/batch |
Batch create leads |
| PUT | /api/v1/leads/batch |
Batch update leads |
| DELETE | /api/v1/leads/batch |
Batch delete leads |
| GET | /api/v1/leads/categories |
Get categories |
| GET | /api/v1/leads/cities |
Get cities |
| POST | /api/v1/leads/score/batch |
Bulk recalculate scores |
| GET | /api/v1/leads/{id} |
Get lead |
| PUT | /api/v1/leads/{id} |
Update lead |
| DELETE | /api/v1/leads/{id} |
Delete lead |
| GET | /api/v1/leads/{id}/changes |
List lead changes |
| POST | /api/v1/leads/{id}/do-not-contact |
Set do not contact |
| DELETE | /api/v1/leads/{id}/do-not-contact |
Clear do not contact |
| POST | /api/v1/leads/{id}/enrich |
Enrich lead |
| POST | /api/v1/leads/{id}/locks/{field} |
Lock lead field |
| DELETE | /api/v1/leads/{id}/locks/{field} |
Unlock lead field |
| POST | /api/v1/leads/{id}/score |
Recalculate score |
| GET | /api/v1/lock-policy |
Get lock policy |
| PUT | /api/v1/lock-policy |
Replace lock policy |
GET /api/v1/leads
Section titled “GET /api/v1/leads”List leads
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. Without it, created_at (also used for an absent or unknown sort_by) lists newest first and other fields ascending. Any other value sorts DESC. |
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. |
limit |
query | no | {"type":"string"} |
Maximum number of leads to return, from 1 to 1000. Default 50. Values above 1000 are capped at 1000; invalid values or values below 1 use 50. |
cursor |
query | no | {"type":"string"} |
Opaque continuation from next_cursor. Notes reject malformed cursors with 400. |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: ListLeadsResponse |
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. |
POST /api/v1/leads
Section titled “POST /api/v1/leads”Creates a lead (201). An email, SIREN, source_id, or phone plus similar name match merges it (200 with duplicate:true). Merges retain existing tags, field locks and do-not-contact state. A name/city potential match creates a new lead with potential_duplicate_id. Storage quota returns 403 leads_limit_reached for new inserts; merges remain allowed.
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
Idempotency-Key |
header | no | {"type":"string","minLength":1,"maxLength":200,"pattern":"^[ -~]+$"} |
Optional retry guard: 1 to 200 printable ASCII characters. A retry with the same key and the same request returns the first response, with Idempotent-Replayed: true, and writes nothing. The same key with a different request returns 409 idempotency_key_reused. A key belongs to its workspace and to the API key that sent it, and is kept 30 days. |
| Request content type | Required | Schema |
|---|---|---|
application/json |
yes | CreateLeadRequest |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: MergeLeadResult |
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.; Idempotent-Replayed: {"type":"string","enum":["true"]} true when this response replays the stored response of an earlier request with the same Idempotency-Key; nothing was written again. |
| 201 | Success | application/json: CreateLeadResult |
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.; Idempotent-Replayed: {"type":"string","enum":["true"]} true when this response replays the stored response of an earlier request with the same Idempotency-Key; nothing was written again. |
| 400 | Request rejected. invalid_idempotency_key when the Idempotency-Key header is not 1 to 200 printable ASCII characters. | application/json: {"oneOf":[{"$ref":"#/components/schemas/Error400"},{"$ref":"#/components/schemas/IdempotencyError400"}]} |
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. |
| 409 | Request rejected. idempotency_key_reused when the Idempotency-Key was already used with a different request; idempotency_key_in_progress, with Retry-After, while a request with the same key is still running. Nothing was written. | application/json: {"oneOf":[{"$ref":"#/components/schemas/Error409"},{"$ref":"#/components/schemas/IdempotencyError409"}]} |
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.; Retry-After: {"type":"integer"} Seconds until retry. Present with idempotency_key_in_progress. |
| 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. |
POST /api/v1/leads/batch
Section titled “POST /api/v1/leads/batch”Batch create leads
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
Idempotency-Key |
header | no | {"type":"string","minLength":1,"maxLength":200,"pattern":"^[ -~]+$"} |
Optional retry guard: 1 to 200 printable ASCII characters. A retry with the same key and the same request returns the first response, with Idempotent-Replayed: true, and writes nothing. The same key with a different request returns 409 idempotency_key_reused. A key belongs to its workspace and to the API key that sent it, and is kept 30 days. |
| Request content type | Required | Schema |
|---|---|---|
application/json |
yes | BatchCreateRequest |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 201 | Success. A write-scoped API key receives WriteKeyBatchCreateResponse. | application/json: {"anyOf":[{"$ref":"#/components/schemas/BatchCreateResponse"},{"$ref":"#/components/schemas/WriteKeyBatchCreateResponse"}]} |
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.; Idempotent-Replayed: {"type":"string","enum":["true"]} true when this response replays the stored response of an earlier request with the same Idempotency-Key; nothing was written again. |
| 207 | Success. A write-scoped API key receives WriteKeyBatchCreateResponse. | application/json: {"anyOf":[{"$ref":"#/components/schemas/BatchCreateResponse"},{"$ref":"#/components/schemas/WriteKeyBatchCreateResponse"}]} |
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.; Idempotent-Replayed: {"type":"string","enum":["true"]} true when this response replays the stored response of an earlier request with the same Idempotency-Key; nothing was written again. |
| 400 | Request rejected. invalid_idempotency_key when the Idempotency-Key header is not 1 to 200 printable ASCII characters. | application/json: {"oneOf":[{"$ref":"#/components/schemas/Error400"},{"$ref":"#/components/schemas/IdempotencyError400"}]} |
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. |
| 409 | Request rejected. idempotency_key_reused when the Idempotency-Key was already used with a different request; idempotency_key_in_progress, with Retry-After, while a request with the same key is still running. Nothing was written. | application/json: IdempotencyError409 |
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.; Retry-After: {"type":"integer"} Seconds until retry. Present with idempotency_key_in_progress. |
| 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. |
PUT /api/v1/leads/batch
Section titled “PUT /api/v1/leads/batch”Batch update leads
Accepted authentication: ApiKey or BearerKey.
| Request content type | Required | Schema |
|---|---|---|
application/json |
yes | BatchUpdateRequest |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: BatchResult |
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. |
| 207 | Success | application/json: BatchResult |
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. |
DELETE /api/v1/leads/batch
Section titled “DELETE /api/v1/leads/batch”Batch delete leads
Accepted authentication: ApiKey or BearerKey.
| Request content type | Required | Schema |
|---|---|---|
application/json |
yes | BatchDeleteRequest |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: BatchResult |
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. |
| 207 | Success | application/json: BatchResult |
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. |
GET /api/v1/leads/categories
Section titled “GET /api/v1/leads/categories”Get categories
Accepted authentication: ApiKey or BearerKey.
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Categories |
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. |
GET /api/v1/leads/cities
Section titled “GET /api/v1/leads/cities”Get cities
Accepted authentication: ApiKey or BearerKey.
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Cities |
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. |
POST /api/v1/leads/score/batch
Section titled “POST /api/v1/leads/score/batch”Bulk recalculate scores
Accepted authentication: ApiKey or BearerKey.
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: BulkScore |
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. |
GET /api/v1/leads/{id}
Section titled “GET /api/v1/leads/{id}”Get lead
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Lead |
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. |
| 404 | Request rejected. | application/json: Error404 |
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. |
| 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. |
PUT /api/v1/leads/{id}
Section titled “PUT /api/v1/leads/{id}”Update lead
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Request content type | Required | Schema |
|---|---|---|
application/json |
yes | UpdateLeadRequest |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success. A write-scoped API key receives WriteKeyReceipt. | application/json: {"anyOf":[{"$ref":"#/components/schemas/Lead"},{"$ref":"#/components/schemas/WriteKeyReceipt"}]} |
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. |
| 404 | Request rejected. | application/json: Error404 |
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. |
| 409 | Request rejected. | application/json: Error409 |
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. |
| 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. |
DELETE /api/v1/leads/{id}
Section titled “DELETE /api/v1/leads/{id}”Delete lead
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 204 | No content | No body | 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. |
GET /api/v1/leads/{id}/changes
Section titled “GET /api/v1/leads/{id}/changes”List lead changes
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
|
limit |
query | no | {"type":"string"} |
Maximum number of changes to return, from 1 to 100. Default 50. Values above 100 are capped at 100; invalid values or values below 1 use 50. |
action |
query | no | {"type":"string"} |
Comma-separated actions to keep, applied before limit, for example created,updated,merged. Absent or empty returns every action. |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Changes |
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. |
POST /api/v1/leads/{id}/do-not-contact
Section titled “POST /api/v1/leads/{id}/do-not-contact”Sets opposition idempotently. Public API keys and classic MCP can set it; OAuth MCP access is unavailable for this operation. Repeated calls keep the original date and origin.
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Lead |
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. |
| 404 | Request rejected. | application/json: Error404 |
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. |
| 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. |
DELETE /api/v1/leads/{id}/do-not-contact
Section titled “DELETE /api/v1/leads/{id}/do-not-contact”Explicit audited removal, allowed only through the dashboard or a public REST API key. MCP access is refused with 403.
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Lead |
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. |
| 404 | Request rejected. | application/json: Error404 |
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. |
| 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. |
POST /api/v1/leads/{id}/enrich
Section titled “POST /api/v1/leads/{id}/enrich”Enrich lead
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Enrichment |
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. |
| 404 | Request rejected. | application/json: Error404 |
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. |
| 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. |
POST /api/v1/leads/{id}/locks/{field}
Section titled “POST /api/v1/leads/{id}/locks/{field}”Lock lead field
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
|
field |
path | yes | {"type":"string","enum":["source","description","address","city","state","country","postal_code","phone","email","website","rating","review_count","category","tags","source_id","siren","logo_url"]} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Lead |
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. |
| 404 | Request rejected. | application/json: Error404 |
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. |
| 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. |
DELETE /api/v1/leads/{id}/locks/{field}
Section titled “DELETE /api/v1/leads/{id}/locks/{field}”Unlock lead field
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
|
field |
path | yes | {"type":"string","enum":["source","description","address","city","state","country","postal_code","phone","email","website","rating","review_count","category","tags","source_id","siren","logo_url"]} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Lead |
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. |
| 404 | Request rejected. | application/json: Error404 |
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. |
| 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. |
POST /api/v1/leads/{id}/score
Section titled “POST /api/v1/leads/{id}/score”Recalculate score
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Score |
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. |
| 404 | Request rejected. | application/json: Error404 |
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. |
| 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. |
GET /api/v1/lock-policy
Section titled “GET /api/v1/lock-policy”The workspace lock policy: the lockable fields and exact custom attribute names frozen after their first value. On each lead created after a name takes effect, the first non-empty value received for it is locked, from any channel. Each entry has the name and effective_at, the Unix second from which it applies. Each list is sorted by name in byte order. A workspace without a policy gets two empty lists. Every member can read it, and so can any API key that can read leads; a write API key or an assistant connection gets 403.
Accepted authentication: ApiKey or BearerKey.
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: LockPolicy |
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. |
PUT /api/v1/lock-policy
Section titled “PUT /api/v1/lock-policy”Replaces the whole policy. fields and attributes are both required, so an omitted list never clears one; send [] to empty a list. Fields must be lockable (see Lock lead field). Attribute names are exact and case-sensitive, 1 to 255 characters, at most 50. A repeated name is stored once. A name kept from the current policy keeps its effective_at; a new or re-added name takes effect when the replace is applied, and only leads created from then on are locked. Existing leads are never locked by the policy, and locks already set stay. Returns the new policy as GET does. Owner or admin, with or without lead access, or a full API key; on the Free plan, only the owner. A viewer, an editor, a read or write API key or an assistant connection gets 403. 400 with a message naming the broken rule. 503 save_temporarily_unavailable when the policy cannot be saved right now: nothing changed, retry after the Retry-After delay. No webhook fires.
Accepted authentication: ApiKey or BearerKey.
| Request content type | Required | Schema |
|---|---|---|
application/json |
yes | ReplaceLockPolicyRequest |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: LockPolicy |
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, or save_temporarily_unavailable: the settings could not be saved right now, and nothing was saved. Retry after the Retry-After delay. | application/json: SourceAlertError503 |
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.; Retry-After: {"type":"integer"} Seconds until retry. Present with save_temporarily_unavailable. |
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."} |
AttributeChange
Section titled “AttributeChange”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
name |
yes | {"type":"string"} |
action |
yes | {"type":"string"} |
reason |
no | {"type":"string"} |
BatchCreateError
Section titled “BatchCreateError”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
index |
yes | {"type":"integer"} |
message |
yes | {"type":"string"} |
BatchCreateRequest
Section titled “BatchCreateRequest”{"type":"object"}
| Field | Required | Schema |
|---|---|---|
leads |
yes | {"type":"array","items":{"$ref":"#/components/schemas/BatchLeadInput"},"minItems":1,"maxItems":500,"description":"Free: at most 100; Pro/Scale: at most 500. Item errors are reported in the batch result."} |
BatchCreateResponse
Section titled “BatchCreateResponse”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
created |
yes | {"type":["array","null"],"items":{"$ref":"#/components/schemas/BatchCreateSuccess"}} |
errors |
yes | {"type":["array","null"],"items":{"$ref":"#/components/schemas/BatchCreateError"}} |
total |
yes | {"type":"integer"} |
success |
yes | {"type":"integer"} |
failed |
yes | {"type":"integer"} |
BatchCreateSuccess
Section titled “BatchCreateSuccess”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
attribute_changes |
no | {"type":["array","null"],"items":{"$ref":"#/components/schemas/AttributeChange"}} |
index |
yes | {"type":"integer"} |
id |
yes | {"type":"string"} |
created_at |
yes | {"type":"integer"} |
duplicate |
no | {"type":"boolean"} |
skipped_locked_fields |
no | {"type":["array","null"],"items":{"type":"string"}} |
warnings |
no | {"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Values the lead was written without, by field and code; the value is never echoed. invalid_email: the email was invalid, so the lead was written without it. Absent when there are none."} |
BatchDeleteRequest
Section titled “BatchDeleteRequest”{"type":"object"}
| Field | Required | Schema |
|---|---|---|
ids |
yes | {"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500,"description":"Free: at most 100; Pro/Scale: at most 500."} |
BatchLeadInput
Section titled “BatchLeadInput”{"type":"object"}
| Field | Required | Schema |
|---|---|---|
enrich |
no | {"type":["boolean","null"]} |
name |
no | {"type":["string","null"]} |
source |
no | {"type":["string","null"]} |
description |
no | {"type":["string","null"]} |
address |
no | {"type":["string","null"]} |
city |
no | {"type":["string","null"]} |
state |
no | {"type":["string","null"]} |
country |
no | {"type":["string","null"]} |
postal_code |
no | {"type":["string","null"]} |
latitude |
no | {"type":["number","null"]} |
longitude |
no | {"type":["number","null"]} |
phone |
no | {"type":["string","null"]} |
email |
no | {"type":["string","null"]} |
website |
no | {"type":["string","null"]} |
rating |
no | {"type":["number","null"]} |
review_count |
no | {"type":["integer","null"]} |
category |
no | {"type":["string","null"]} |
tags |
no | {"type":["array","null"],"items":{"type":"string"}} |
source_id |
no | {"type":["string","null"]} |
siren |
no | {"type":["string","null"]} |
logo_url |
no | {"type":["string","null"]} |
status |
no | {"type":["string","null"],"maxLength":50,"description":"Lead status, stored as sent; defaults to new when absent or empty. The workspace's status list names the expected values (GET /statuses); the examples are the five defaults. Other values are kept and reported as unlisted. A duplicate merge never changes it.","examples":["new","contacted","qualified","disqualified","converted"]} |
assignee |
no | {"type":["string","null"],"description":"Email of the workspace owner or an active member to assign the lead to, matched case-insensitively. Null or empty leaves the lead unassigned. Anyone else is refused with assignee_not_member. A duplicate merge never changes the assignee."} |
attributes |
no | {"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateAttributeRequest"}} |
do_not_contact |
no | {"type":["boolean","null"]} |
BatchResult
Section titled “BatchResult”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
results |
yes | {"type":"array","items":{"$ref":"#/components/schemas/BatchUpdateResult"}} |
total |
yes | {"type":"integer"} |
success |
yes | {"type":"integer"} |
failed |
yes | {"type":"integer"} |
warnings |
no | {"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Batch update only: the warnings of data, which applies to every lead; see PUT /leads/{id}. Absent when there are none."} |
BatchUpdateRequest
Section titled “BatchUpdateRequest”{"type":"object"}
| Field | Required | Schema |
|---|---|---|
ids |
yes | {"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500,"description":"Free: at most 100; Pro/Scale: at most 500."} |
data |
no | UpdateLeadRequest |
BatchUpdateResult
Section titled “BatchUpdateResult”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
index |
yes | {"type":"integer"} |
id |
yes | {"type":"string"} |
success |
yes | {"type":"boolean"} |
message |
no | {"type":"string"} |
BulkScore
Section titled “BulkScore”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
updated |
yes | {"type":"integer"} |
Categories
Section titled “Categories”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
categories |
yes | {"type":["array","null"],"items":{"type":"string"}} |
count |
yes | {"type":"integer"} |
Changes
Section titled “Changes”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
changes |
yes | {"type":"array","items":{"$ref":"#/components/schemas/LeadChange"}} |
count |
yes | {"type":"integer"} |
Cities
Section titled “Cities”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
cities |
yes | {"type":["array","null"],"items":{"type":"string"}} |
count |
yes | {"type":"integer"} |
CreateAttributeRequest
Section titled “CreateAttributeRequest”{"type":"object","additionalProperties":true}
| Field | Required | Schema |
|---|---|---|
id |
no | {"type":["string","null"]} |
name |
no | {"type":["string","null"]} |
type |
no | {"type":["string","null"]} |
value |
no | {} |
CreateLeadRequest
Section titled “CreateLeadRequest”{"type":"object"}
| Field | Required | Schema |
|---|---|---|
enrich |
no | {"type":["boolean","null"]} |
name |
yes | {"type":"string","minLength":1,"description":"Surrounding whitespace is removed; a name made only of whitespace is refused with name is required.","pattern":"[^\t\n\u000b\u000c\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]"} |
source |
yes | {"type":"string","minLength":1} |
description |
no | {"type":["string","null"]} |
address |
no | {"type":["string","null"]} |
city |
no | {"type":["string","null"]} |
state |
no | {"type":["string","null"]} |
country |
no | {"type":["string","null"]} |
postal_code |
no | {"type":["string","null"]} |
latitude |
no | {"type":["number","null"]} |
longitude |
no | {"type":["number","null"]} |
phone |
no | {"type":["string","null"]} |
email |
no | {"type":["string","null"]} |
website |
no | {"type":["string","null"]} |
rating |
no | {"type":["number","null"]} |
review_count |
no | {"type":["integer","null"]} |
category |
no | {"type":["string","null"]} |
tags |
no | {"type":["array","null"],"items":{"type":"string"}} |
source_id |
no | {"type":["string","null"]} |
siren |
no | {"type":["string","null"]} |
logo_url |
no | {"type":["string","null"]} |
status |
no | {"type":["string","null"],"maxLength":50,"description":"Lead status, stored as sent; defaults to new when absent or empty. The workspace's status list names the expected values (GET /statuses); the examples are the five defaults. Other values are kept and reported as unlisted. A duplicate merge never changes it.","examples":["new","contacted","qualified","disqualified","converted"]} |
assignee |
no | {"type":["string","null"],"description":"Email of the workspace owner or an active member to assign the lead to, matched case-insensitively. Null or empty leaves the lead unassigned. Anyone else is refused with assignee_not_member. A duplicate merge never changes the assignee."} |
attributes |
no | {"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateAttributeRequest"}} |
do_not_contact |
no | {"type":["boolean","null"]} |
CreateLeadResult
Section titled “CreateLeadResult”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
attribute_changes |
no | {"type":["array","null"],"items":{"$ref":"#/components/schemas/AttributeChange"}} |
id |
yes | {"type":"string"} |
message |
yes | {"type":"string"} |
created_at |
no | {"type":"integer","description":"Absent for a write-scoped API key."} |
duplicate |
no | {"const":false} |
potential_duplicate_id |
no | {"type":"string","description":"Absent for a write-scoped API key."} |
skipped_locked_fields |
no | {"type":["array","null"],"items":{"type":"string"}} |
warnings |
no | {"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Values the lead was written without, by field and code; the value is never echoed. invalid_email: the email was invalid, so the lead was written without it. Absent when there are none."} |
Enrichment
Section titled “Enrichment”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
lead |
yes | Lead |
enriched |
yes | {"type":"boolean"} |
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}]}
Error404
Section titled “Error404”{"oneOf":[{"type":"object","properties":{"error":{"const":"not_found"},"code":{"const":"not_found"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error409
Section titled “Error409”{"oneOf":[{"type":"object","properties":{"error":{"const":"conflict"},"code":{"const":"conflict"},"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}]}
IdempotencyError400
Section titled “IdempotencyError400”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
error |
yes | {"const":"invalid_idempotency_key"} |
code |
yes | {"const":"invalid_idempotency_key"} |
message |
yes | {"type":"string"} |
IdempotencyError409
Section titled “IdempotencyError409”{"oneOf":[{"type":"object","properties":{"error":{"const":"idempotency_key_reused"},"code":{"const":"idempotency_key_reused"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"idempotency_key_in_progress"},"code":{"const":"idempotency_key_in_progress"},"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."} |
LeadChange
Section titled “LeadChange”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
id |
yes | {"type":"string"} |
lead_id |
yes | {"type":"string"} |
actor_id |
no | {"type":["string","null"]} |
api_key_id |
no | {"type":["string","null"],"description":"The API key behind the change, for a write made with an API key (REST or classic MCP). The id stays after the key is revoked."} |
action |
yes | {"type":"string","description":"What changed. A scored entry records a stored score change; its before and after hold only score. An attribute write is an updated entry with reason attribute:<name> and the lead before and after. A note.created, note.updated or note.deleted entry holds the note before and after; deleting a lead writes one note.deleted entry per note, with reason lead:deleted. An assigned entry records a new assignee and an unassigned entry a cleared one; their before and after are empty.","examples":["created","updated","merged","deleted","scored","note.created","note.updated","note.deleted","assigned","unassigned"]} |
assignee |
no | {"type":"string","description":"Email of the new assignee, on an assigned entry. Absent once that person's account is deleted or once the history is erased."} |
changed_fields |
no | {"type":"array","items":{"type":"string"},"description":"Names of the top-level fields the entry changed, sorted, plus assignee on an assigned or unassigned entry. Present only once the history is erased: within 31 days of a lead's deletion, a daily job erases before, after and assignee, which are then absent. The action, created_at, actor_id, api_key_id, channel and reason stay. Absent on every other entry."} |
channel |
no | {"type":"string","description":"How the lead arrived, on the entries a create or a duplicate merge recorded, in GET /leads/{id}/changes: api (POST /leads with an API key), api_batch (POST /leads/batch with an API key), mcp_classic (MCP with an API key), dashboard (created in the dashboard), import (dashboard import, CSV or JSON), save_leads (an AI assistant connected with OAuth) or inbound (a row a tool posted to an inbound webhook URL). Klozeo sets it from the credential and the route; no request field sets it. Absent on older entries, on other entries, and in the account export.","enum":["api","api_batch","mcp_classic","dashboard","import","save_leads","inbound"]} |
before |
no | {} |
after |
no | {} |
created_at |
yes | {"type":"integer"} |
user_id |
yes | {"type":"string","description":"Alias of workspace_id, kept for existing integrations."} |
workspace_id |
yes | {"type":"string","description":"The workspace the entry belongs to."} |
reason |
no | {"type":"string"} |
ListLeadsResponse
Section titled “ListLeadsResponse”{"type":"object","additionalProperties":false,"allOf":[{"if":{"properties":{"has_more":{"const":true}}},"then":{"required":["next_cursor"],"properties":{"next_cursor":{"minLength":1}}}}]}
| Field | Required | Schema |
|---|---|---|
leads |
yes | {"type":["array","null"],"items":{"$ref":"#/components/schemas/Lead"}} |
next_cursor |
no | {"type":"string"} |
has_more |
yes | {"type":"boolean"} |
count |
yes | {"type":"integer"} |
LockPolicy
Section titled “LockPolicy”{"type":"object","description":"The workspace lock policy. Each list is sorted by name in byte order.","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
fields |
yes | {"type":"array","description":"Lockable lead fields frozen after their first value, on leads created after each name takes effect.","items":{"$ref":"#/components/schemas/LockPolicyEntry"}} |
attributes |
yes | {"type":"array","description":"Exact, case-sensitive custom attribute names frozen after their first value, on leads created after each name takes effect.","items":{"$ref":"#/components/schemas/LockPolicyEntry"}} |
LockPolicyEntry
Section titled “LockPolicyEntry”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
name |
yes | {"type":"string","description":"The field name, or the exact custom attribute name."} |
effective_at |
yes | {"type":"integer","description":"Unix seconds: when the name was added to the policy. Leads created from then on are covered. It stays the same while the name stays listed; a name removed and added again gets a new one."} |
MergeLeadResult
Section titled “MergeLeadResult”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
attribute_changes |
no | {"type":["array","null"],"items":{"$ref":"#/components/schemas/AttributeChange"}} |
id |
yes | {"type":"string"} |
message |
yes | {"type":"string"} |
created_at |
no | {"type":"integer","description":"Absent for a write-scoped API key."} |
duplicate |
yes | {"const":true} |
potential_duplicate_id |
no | {"type":"string","description":"Absent for a write-scoped API key."} |
skipped_locked_fields |
no | {"type":["array","null"],"items":{"type":"string"}} |
warnings |
no | {"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Values the lead was written without, by field and code; the value is never echoed. invalid_email: the email was invalid, so the lead was written without it. Absent when there are none. On a merge the stored email is kept."} |
{"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."} |
ReplaceLockPolicyRequest
Section titled “ReplaceLockPolicyRequest”{"type":"object","description":"The whole new policy. Both lists are required.","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
fields |
yes | {"type":"array","description":"Every field to lock, each a lockable field. Send [] for none.","items":{"type":"string"}} |
attributes |
yes | {"type":"array","description":"Every custom attribute name to lock: exact and case-sensitive, 1 to 255 characters each, at most 50. Send [] for none.","items":{"type":"string"}} |
{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
id |
yes | {"type":"string"} |
score |
yes | {"type":"number"} |
SourceAlertError503
Section titled “SourceAlertError503”{"oneOf":[{"$ref":"#/components/schemas/Error503"},{"type":"object","properties":{"error":{"const":"save_temporarily_unavailable"},"code":{"const":"save_temporarily_unavailable"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
UpdateLeadRequest
Section titled “UpdateLeadRequest”{"type":["object","null"]}
| Field | Required | Schema |
|---|---|---|
name |
no | {"type":["string","null"],"description":"Surrounding whitespace is removed; a name made only of whitespace is refused with name is required.","pattern":"[^\t\n\u000b\u000c\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]"} |
source |
no | {"type":["string","null"]} |
description |
no | {"type":["string","null"]} |
address |
no | {"type":["string","null"]} |
city |
no | {"type":["string","null"]} |
state |
no | {"type":["string","null"]} |
country |
no | {"type":["string","null"]} |
postal_code |
no | {"type":["string","null"]} |
latitude |
no | {"type":["number","null"]} |
longitude |
no | {"type":["number","null"]} |
phone |
no | {"type":["string","null"]} |
email |
no | {"type":["string","null"]} |
website |
no | {"type":["string","null"]} |
rating |
no | {"type":["number","null"]} |
review_count |
no | {"type":["integer","null"]} |
category |
no | {"type":["string","null"]} |
tags |
no | {"type":["array","null"],"items":{"type":"string"}} |
source_id |
no | {"type":["string","null"]} |
siren |
no | {"type":["string","null"]} |
logo_url |
no | {"type":["string","null"]} |
status |
no | {"type":["string","null"],"maxLength":50,"description":"Lead status, stored as sent. The workspace's status list names the expected values (GET /statuses); the examples are the five defaults. Other values are kept and reported as unlisted.","examples":["new","contacted","qualified","disqualified","converted"]} |
assignee |
no | {"type":["string","null"],"description":"Email of the workspace owner or an active member to assign the lead to, matched case-insensitively. Null or empty clears the assignee. Anyone else is refused with assignee_not_member; sending the current assignee again is accepted, even once they left the workspace."} |
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."} |
WriteKeyBatchCreateResponse
Section titled “WriteKeyBatchCreateResponse”{"type":"object","description":"What a write-scoped API key receives from a batch create: ids and outcomes, never a stored value.","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
created |
yes | {"type":"array","items":{"$ref":"#/components/schemas/WriteKeyBatchCreateSuccess"}} |
errors |
yes | {"type":"array","items":{"$ref":"#/components/schemas/BatchCreateError"}} |
total |
yes | {"type":"integer"} |
success |
yes | {"type":"integer"} |
failed |
yes | {"type":"integer"} |
WriteKeyBatchCreateSuccess
Section titled “WriteKeyBatchCreateSuccess”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
index |
yes | {"type":"integer"} |
id |
yes | {"type":"string"} |
duplicate |
no | {"type":"boolean"} |
attribute_changes |
no | {"type":["array","null"],"items":{"$ref":"#/components/schemas/AttributeChange"}} |
skipped_locked_fields |
no | {"type":["array","null"],"items":{"type":"string"}} |
warnings |
no | {"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Values the lead was written without, by field and code; the value is never echoed. invalid_email: the email was invalid, so the lead was written without it. Absent when there are none."} |
WriteKeyReceipt
Section titled “WriteKeyReceipt”{"type":"object","description":"What a write-scoped API key receives instead of the stored object: the id of what it wrote and the outcome, never a stored value.","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
id |
yes | {"type":"string"} |
message |
yes | {"type":"string","examples":["Lead updated","Note created","Note updated","Attribute created"]} |
warnings |
no | {"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"Lead update only: see the warnings of PUT /leads/{id}."} |