Common API behavior

Use this page when you are wiring up any KickoffLabs API endpoint.

Base URL

Most current API endpoints use:

https://api.kickofflabs.com/v2

Endpoint examples:

• POST /v2/{campaign_id} creates or updates a lead.
• GET /v2/{campaign_id} looks up a lead.
• GET /v2/campaigns lists campaigns for an API key.
• POST /v2/{campaign_id}/outbound-webhook creates an outbound webhook.

Some older embed and form flows still use /v1 or /subscribe style URLs. Prefer the /v2 endpoints for new server-side integrations.

Authentication

Protected API endpoints require an api_key.

You can pass the API key in one of these ways:

• As a request parameter named api_key.
• For JSON requests, in an Authorization header such as Bearer YOUR_API_KEY.
• For JSON requests, in an Authentication header. KickoffLabs uses the final whitespace-separated token from either header.

curl -X POST "https://api.kickofflabs.com/v2/CAMPAIGN_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer KEY" \
  -d '{"email":"ada@example.com"}'

Note

Some campaign settings allow unauthenticated browser signups for embed/form flows. Server-side API integrations should always send an API key.

Request formats

KickoffLabs accepts JSON request bodies for API endpoints. Many endpoints also accept form/query parameters because the API normalizes request parameters internally.

For JSON requests, send:

Content-Type: application/json

Invalid JSON returns an error message telling you to verify the JSON payload.

Campaign identifiers

In these docs, CAMPAIGN_ID is the campaign/list id. The app also accepts campaign_id, campaignId, list_id, and __lid internally for many endpoints, but the path form is clearer for /v2 API calls.

Lead identifiers

Depending on the endpoint, a lead can be identified by:

• email
• phone_number
• kid or social_id

Bulk endpoints accept only one identifier type per request. Do not mix emails, phone numbers, and social ids in the same bulk update.

Common status codes

• 200 OK: Request completed immediately.
• 202 Accepted: Bulk work was queued for asynchronous processing.
• 400 Bad Request: No matching leads/items were found for a bulk change or delete.
• 404 Not Found: The campaign, lead, action, or webhook was not found.
• 406 Not Acceptable: Lead parameters failed validation, such as missing email/phone or invalid email/phone format.
• 409 Conflict: Invalid API access, missing API key, missing required input, invalid update action, invalid event type, or a campaign/account state that blocks the request.
• 413 Payload Too Large: More than 250 items were submitted to a bulk endpoint.
• 422 Unprocessable Entity: Lead creation/update failed validation after processing.
• 423 Locked: The campaign has ended and no longer accepts new leads or scoring.
• 429 Too Many Requests: Rate limit exceeded.

Rate limits

Rate limits are enforced for API traffic. Practical defaults include:

• Unauthenticated campaign GET requests by IP: 100 per minute, 200 per 3 minutes, and 300 per 9 minutes.
• Unauthenticated campaign POST requests by IP: 10 per minute, 20 per 3 minutes, and 30 per 9 minutes.
• Global unauthenticated POST requests by IP: 50 per minute.
• DELETE requests: 60 per minute by account.
• Authenticated account GET/POST limits are based on the account’s campaign conversion limit or account-specific override.

If you are doing a large import or expect bursty traffic, contact support before launching.

CORS

The public API sets Access-Control-Allow-Origin: * and supports preflight OPTIONS requests for browser-based integrations.

Common lead response fields

Lead create, lookup, webhook, and internal lead responses share a common lead payload. Common fields include:

• id: Numeric lead id for most sources. For API-created leads, this may be the lead’s social_id.
• social_id: Public referral/social id used in kid links.
• campaign_id and list_id: Campaign/list id.
• rank, rank_relative_position, counter, lead_count, subscription_number: Signup/order and campaign count values.
• contest_score, contest_score_rank, contest_score_rank_relative_position: Contest score data.
• first_name, given_name, family_name, display_name, avatar: Display fields.
• verified, verified_email, verified_phone_number, waitlisted: Lead status fields.
• social_url, redirect_url, thankyou_url, status_url: URLs for the lead experience, unless URL fields are skipped.
• completed_actions: Campaign action ids completed by the lead, unless action fields are skipped.
• email, phone_number, custom_fields, uid, parent_id, opted_out, sms_opted_out, utm, tags: PII and account-specific data. Campaign privacy settings may suppress these unless the request is authenticated.
• referrals, unverified_leads, verified_leads, influence: Referral counts.
• ip, referrer, fraudulent: Returned for authenticated requests.

Optional response controls

Some internal parameters affect response shape:

• __skip_urls=1: Omits URL fields such as social_url, redirect_url, thankyou_url, status_url, and unsubscribe_url.
• __skip_actions=1: Omits completed_actions.

These are most useful for integrations that only need the core lead record.