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.

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.

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."
      }
    }
  ]
}