Skip to content
Docs
Back to KickoffLabs

Create or Update a New Lead

POST https://api.kickofflabs.com/v2/CAMPAIGN_ID/

Creates a new lead or updates an existing lead in a campaign.

Authentication

Section titled “Authentication”

Send your API key as api_key or, for JSON requests, in an Authorization or Authentication header. See Common API behavior for details.

Required Parameters

Section titled “Required Parameters”
  • email or phone_number: At least one is required.

You can supply both email and phone_number when you have both.

Optional Parameters

Section titled “Optional Parameters”
  • api_key: Your account API key. Recommended for all server-side integrations.
  • ip: The lead’s IP address. If omitted, KickoffLabs uses the request IP.
  • __url: The URL where the lead signed up. If this URL contains query parameters, KickoffLabs can merge those parameters into the request data.
  • __referrer: The referrer URL. Older integrations may use referrer.
  • __source: Source tracking. Values in the form source.id, such as modal.123, can attach the request to a source id.
  • __uid: Optional external/user id.
  • __sid or __session_id: Optional session id.
  • __rid: Optional request id.
  • __skip_urls=1: Omit URL fields from the response.
  • __skip_actions=1: Omit completed action ids from the response.
  • __do_not_reset_opt_out: When updating an existing opted-out lead, do not reset the opt-out flag.
  • must_exist: If true, only update an existing lead. If no matching lead exists, no new lead is created.
  • redirect_url: Optional redirect URL stored with the request.
  • points: Custom points can be accepted only when the request is authorized with an API key.
  • phone_number: A phone number for SMS-enabled campaigns. If country_code is also provided, it is prepended to the phone number before validation.

Custom Fields

Section titled “Custom Fields”

Any remaining parameters that are not reserved API fields are captured as custom fields. Field names are normalized to lowercase strings.

KickoffLabs removes internal/reserved fields before saving custom fields, including controller/action metadata, ids such as list_id, landing_page_id, kid, kolid, ip, ip_address, and email; private fields beginning with _; and UTM fields beginning with utm_.

Update behavior

Section titled “Update behavior”

If a matching lead already exists, KickoffLabs updates that record instead of creating a duplicate. Existing leads are matched by the submitted email, phone number, or social id depending on the request data.

When an existing lead is updated:

  • The lead’s counter is incremented.
  • If the lead was opted out, the opt-out flag is reset unless __do_not_reset_opt_out is provided.
  • If the existing lead only had a phone number, a submitted email can be added.
  • If the existing lead did not have a phone number, a submitted phone number can be added.

Validation and errors

Section titled “Validation and errors”
  • Missing both email and phone_number returns a validation error.
  • Invalid email format returns a validation error.
  • Invalid phone number format returns a validation error.
  • A missing campaign returns 404.
  • Invalid API access returns 409.
  • If the campaign has ended and no longer accepts new leads, KickoffLabs returns 423.

Example request

Section titled “Example request”
Terminal window
curl -X POST "https://api.kickofflabs.com/v2/CAMPAIGN_ID/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer KEY" \
  -d '{
    "email": "ada@example.com",
    "phone_number": "+12065550100",
    "first_name": "Ada",
    "company": "Example Co"
  }'

Example response

Section titled “Example response”

Successful requests return a lead payload. See Create Lead API Response for the field reference.