Campaigns API Documentation

Campaign Management

The Campaigns API lets connected tools create draft campaigns, add leads, list and inspect lifecycle state, pause or end campaigns, use Fast Forward on nearly complete campaigns, and reopen ended campaigns using your Organization API Key.

Create campaigns

Create a draft campaign with leads, sending schedule, and automated email sequence steps.

Add leads

Add leads to an existing campaign while applying the same dedupe and validation rules.

Inspect and manage lifecycle

List by exact status or lifecycle scope, inspect available actions, pause or end campaigns, use Fast Forward on nearly complete campaigns, and reopen ended campaigns.

Base URL and Authentication

All requests use the standard bearer token header.

https://beam.lightmeter.io
Authorization: Bearer your_api_key_here

Example Request

POST

/api/v1/campaigns/submit

curl -X POST https://beam.lightmeter.io/api/v1/campaigns/submit \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "Product Launch Outreach",
    "schedule": {
      "timezone": "America/New_York",
      "days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
      "daily_start_time": "09:00",
      "daily_end_time": "17:00"
    },
    "lead_dedupe_scope": "all_campaigns",
    "leads": [
      {
        "email": "contact@example.com",
        "first_name": "Alex",
        "last_name": "Johnson",
        "company_name": "TechCorp Inc",
        "contact_linkedin_url": "https://linkedin.com/in/alexjohnson",
        "account_linkedin_url": "https://linkedin.com/company/techcorp",
        "timezone": "Pacific Standard Time",
        "attributes": {
          "job_title": "VP of Engineering",
          "industry": "Technology",
          "custom_note": "Interested in automation tools"
        }
      }
    ],
    "sequence": [
      {
        "step": 1,
        "type": "new",
        "variants": [
          {
            "subject": [
              "Quick question for {{first_name}}",
              "An idea for {{company_name}}",
              "Worth comparing notes?",
              "One practical question"
            ],
            "body": "Hi {{first_name}}, I noticed your recent work at {{company_name}}..."
          }
        ]
      }
    ]
  }'

Key Validation Rules

Schedule: valid IANA timezone, unique days, HH:MM time format, and start time before end time.
Leads: no duplicate emails; LinkedIn URLs must start with http:// or https:// and contain linkedin.com.
Attributes: keys must be alphanumeric with _ or - only, up to 100 characters. Reserved keys include id, customer_id, email, first_name, last_name, company, company_name, linkedin_url, timezone, created_at, and updated_at.
Sequence: steps must be sequential with no gaps or duplicates.
Variants: variants are labeled by array position. A new-message variant can have up to 26 ordered subject options above one shared body. Enabled subjects are selected uniformly; threaded follow-ups inherit the parent subject and support one body variant.
Dedupe policy: optional lead_dedupe_scope must be none, active_campaigns, all_campaigns, or all_audiences. Omitted or empty values default to none.
Completion deadline: requests may send an exact RFC3339 timestamp, or a legacy YYYY-MM-DD value when a valid campaign timezone is included in the schedule. Responses keep completion_deadline as date-only for compatibility and expose the exact stored cut-off in completion_deadline_at.
Workspace suppression: explicit unsubscribe replies add the recipient email to the workspace email blocklist. Remove that blocklist entry before intentionally contacting the recipient again from a future campaign.

Prepare the Creative Working Copy

Begin with GET /api/v1/campaigns/{campaign_id}/creative. It returns target-labelled Default and adaptation documents plus the server-owned adaptations_activated capability; the capability is not a client request flag or response filter. Use the Creative endpoints to save one or more numbered subjects above each shared body, plus planned subject eligibility, variants, step delays, and threading settings before approval. Updating Creative saves immutable snapshot history but does not change the Ready Creative used for future sends.

PUT

/api/v1/campaigns/{campaign_id}/creative

curl -X PUT https://beam.lightmeter.io/api/v1/campaigns/550e8400-e29b-41d4-a716-446655440000/creative \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "overwrite_existing": true,
    "documents": [
      {
        "step_number": 1,
        "variant_number": 1,
        "field_type": "subject",
        "subject_number": 1,
        "plain_text": "Quick question for {{first_name}}"
      },
      {
        "step_number": 1,
        "variant_number": 1,
        "field_type": "subject",
        "subject_number": 2,
        "is_disabled": true,
        "plain_text": "An idea for {{company_name}}"
      },
      {
        "step_number": 1,
        "variant_number": 1,
        "field_type": "body",
        "subject_number": 1,
        "plain_text": "Hi {{first_name}}, noticed your work at {{company_name}}..."
      }
    ],
    "step_settings": [
      {
        "step_number": 2,
        "wait_days": 3,
        "is_threaded": true
      }
    ]
  }'

Creative Approval

Call POST /api/v1/campaigns/{campaign_id}/creative/approve when the current Creative working copy should become an immutable approved snapshot and be marked Ready for future sends. Existing Creative fields are protected from accidental overwrite unless overwrite_existing is true. New subject numbers must leave each body with a contiguous set starting at 1; one request may provide a complete batch in any array order. Optional is_disabled on subject documents plans eligibility for the next Ready Creative. Use PATCH /api/v1/campaigns/{campaign_id}/subjects/{subject_id} to change one current Ready subject without editing or reapproving the shared body.

Review Existing Lead Corrections

Submit the complete campaign or add-leads request with preview_only: true. The response names other affected campaigns and compares current and imported values. When confirmation_required is true, obtain an explicit choice, then resend the unchanged request with preview_only: false, review_token from review.token, and decision: "overwrite" or "preserve". A stale review must be reviewed again. Current-campaign-only and finished-only changes do not require an extra decision.

Successful apply responses can contain failed rows. Inspect row_outcomes for every input row: conflicting identities are left unapplied while independently valid rows proceed. Do not retry successful rows. Blank imported values do not erase existing details, and choosing overwrite never merges different people. The user manual explains shared values and finished campaigns.