Lightmeter Leads API

Safe upsert workflow

Send up to 2,000 structured records to POST /api/v1/leads/imports/preview.
Review row-level errors, protected values, replacements, creations, and audience membership effects.
Repeat the unchanged request at POST /api/v1/leads/imports with the returned review and audience plan tokens plus a new operation UUID.
If either existing-attribute policy is overwrite and the preview includes replacements, explicitly set confirm_overwrite to true.

Missing leads are created by default. Existing standard and custom attribute values are preserved by default. Omitting an attribute leaves it untouched; null and empty-string clearing are not supported by this version.

A mutating apply reserves its operation_id and can recover the exact committed result on retry. A true no-op has no import history to recover, so it returns an empty import_id with operation_id_reserved=false; repeating that no-op is harmless, and the unreserved UUID may later be used for a different mutating request.

Workspace lead management

Organization API keys can use the same workspace lead workflows as the browser. Every path below is scoped to the key's workspace. Lead lists and reply history exclude soft-deleted leads.

GET /api/v1/lens/leads searches and filters leads. Use q, company, email, has_replied, reply_polarity, RFC3339 created_after/created_before, and comma-separated UUID tag_ids. Continue with next_cursor; each page supports up to 1,000 leads, and total_count appears on the first page only. Restart from page one if an edited lead invalidates the cursor boundary.
GET /api/v1/lens/leads/:lead_id/reply-history returns campaign send and qualified reply history. Use reply_limit, reply_cursor (at most 4,096 bytes), and campaign_limit for bounded reads.
GET /api/v1/lens/leads/export/csv/page returns a JSON CSV page with has_more and next_cursor; follow the cursor to export all matching leads, at most 100 per page. Pass the opaque cursor unchanged with the same sort options; restart from page one if an edited lead invalidates the cursor boundary. total_count appears on the first page only. Spreadsheet formula prefixes are escaped.
POST /api/v1/lens/leads/bulk-delete soft-deletes 1–1,000 selected UUIDs with JSON {"lead_ids":["..."],"confirm_delete":true}. The result reports how many active leads were deleted. Review the exact selection before calling; unrelated workspace IDs have no effect.

Workspace lead CSV import and undo

Use multipart/form-data with a file ending in .csv. The CSV limit is 10 MiB and 10,000 rows; API and MCP multipart requests have an 11 MiB total body limit to leave room for review fields. This workflow shares the browser's mapping, conflict, and reversible-history rules.

POST /api/v1/lens/leads/import/preview returns detected columns and sample rows without writing.
POST /api/v1/lens/leads/import/impact accepts the CSV and optional JSON column_mappings, then returns the current create, update, unchanged, failed, and overwrite impact.
POST /api/v1/lens/leads/import repeats the same CSV and mappings with expected_impact from review and a client-generated operation_id UUID. Reuse that UUID only to retry an unchanged request. Add confirm_overwrite=true when the reviewed plan replaces existing values. The server refuses stale impact.
GET /api/v1/lens/leads/import/history lists recent imports. For a reversible import, POST /api/v1/lens/leads/import/:import_id/undo with JSON {"confirm_undo":true} attempts a conflict-aware undo and reports any rows or audience changes that could not be reversed.

Use GET /api/v1/lens/leads/import/template for the CSV template. Workspace API CSV imports do not accept campaign assignments; use the campaign lead API for those actions.

Audience assignment

Define audience targets once under request-local refs. Use default_audience_refs for the common all-leads case, or set audience_refs on individual records to assign different audiences in one operation. An explicit empty per-lead array opts that record out. Membership is additive: omission never removes a lead from an audience.

Static audiences may contain email-less or LinkedIn-only leads. Campaign eligibility is evaluated separately when a campaign uses an audience.

Manage static audiences

Organization API keys can list and create audiences with GET and POST /api/v1/audiences. Create accepts a name of at most 255 bytes, optional description of at most 4,096 bytes, and 1–2,000 existing active workspace lead UUIDs in a request of at most 1 MiB. The response reports the audience UUID and how many leads were added; lead IDs from another workspace are never added. Use GET /api/v1/audiences/{audience_id} for details and GET /api/v1/audiences/{audience_id}/leads for active members. To remove an audience and its memberships while retaining the leads, send DELETE /api/v1/audiences/{audience_id} with JSON {"confirm_name":"Exact current audience name"}; a missing or mismatched name is rejected.

List endpoints accept limit from 1 to 100 and a nonnegative offset; omitted values default to 100 and 0. The API key must belong to the target workspace. Audience IDs from other workspaces return not found.

To create an audience from a CSV, upload multipart form data to POST /api/v1/audiences/from-csv/preview for headers, sample rows, and suggested mappings. Then send the same file, a name, optional description and JSON column_mappings to POST /api/v1/audiences/from-csv with preview_only=true. The returned review.token is required for an API-key apply. Repeat the unchanged input with review_token; when the review shows changes to existing lead details, explicitly send decision=preserve or decision=overwrite. Preserve keeps existing populated values. Programmatic uploads are limited to 10 MiB and 100,000 CSV data rows.

Programmatic review and apply responses include at most 50 row_outcomes per response. Set row_offset, campaign_offset, and row_limit (1–50) in the multipart form to select a review page; the response reports totals and has_more_rows/has_more_campaigns. Re-preview the same file with another offset to inspect later rows before applying. Apply returns a single selected outcome page and final counts; do not repeat apply to fetch another page because that would create another audience.

Add to a workspace blocklist

Use POST /api/v1/blocklists/values with your organization API key to block email addresses or whole domains in that key's workspace. Set type to email or domain and supply 1–500 values. One request can be at most 256 KiB. A separate request is needed for each type.

{
  "type": "email",
  "values": ["lead@example.com", "other@example.com"]
}

The response reports each input row as added, duplicate, or invalid. Repeating a successfully added value returns duplicate without a second active block. Valid rows still succeed when another row is invalid. The request blocks values across the workspace at send time; it does not take a lead ID, unsubscribe a lead, or reopen an already skipped campaign lead.

Read active blocks with GET /api/v1/blocklists/values?type=email. Filter with search or source, choose sort=asc|desc, and page with limit (1–200, default 25) and offset (default 0). The response includes the matching total and source options. Remove one or several with DELETE /api/v1/blocklists/values, a type, 1–500 values, and confirm: true. Removal returns removed, not_found, duplicate, or invalid for each input row. Repeating a removal is safe and returns not_found. These operations use the organization API key's own workspace; the corresponding signed-in controls require a workspace owner or admin.

Preview a CSV using POST /api/v1/blocklists/values/import/preview with JSON {"type":"email","csv":"email\nlead@example.com\n"}, then use POST /api/v1/blocklists/values/import to add inactive values. Each call accepts up to 2,000 nonempty rows and 1 MiB of encoded JSON; valid rows succeed while duplicate and invalid rows are counted. Repeating the import does not create a second active block. Download matching values with GET /api/v1/blocklists/values/export?type=email; search, source, and repeated exclude_canonical_value filters are supported. CSV exports are limited to 128 MiB; narrow larger exports with those filters. The API generates at most two exports at once and serves at most eight concurrent downloads per process; excess requests return 429 with Retry-After. CSV values are protected against spreadsheet formula interpretation. Export CSV includes value_formula_escaped so importing the downloaded CSV restores addresses beginning with a formula-like character without changing genuine leading apostrophes.

Lead attribute terminology

Standard attributes are schema-defined lead data such as names, emails, LinkedIn URL, title, company name, and timezone. Custom attributes are workspace-defined string values used for enrichment and personalization. Lead IDs and source are system metadata; audience and campaign relationships are memberships. Neither belongs in an attribute object.

Example preview

{
  "source_name": "School prospect enrichment",
  "existing_custom_attribute_policy": "preserve",
  "audiences": [
    { "ref": "connecticut", "name": "Connecticut prospects", "if_missing": "create" }
  ],
  "default_audience_refs": ["connecticut"],
  "leads": [
    {
      "source_ref": "crm:northstar-academy",
      "standard_attributes": {
        "work_email": "admissions@example.edu",
        "company_name": "Northstar Academy"
      },
      "custom_attributes": {
        "peer_schools": "Lakeside Academy; Redwood School",
        "peer_school_sentence": "We work with Lakeside Academy and Redwood School."
      }
    }
  ]
}