---
title: "Add a lead to the database"
method: POST
path: "/api/v1/leads"
tags: ["Leads"]
---

# Add a lead to the database

`POST /api/v1/leads`

## Request

- Base URL: `https://api.checkcherry.com`
- URL: `https://api.checkcherry.com/api/v1/leads`
- Auth: none declared. Required headers: `Api-Key`

Creates a new lead for the specified business. A lead represents a potential customer inquiry that can later be converted into a confirmed event.

At minimum, an `email` address is required. All other fields are optional but recommended for a complete lead record.

The `staff_id` field requests a staff member for the lead's package. It carries through to the booking when the lead converts. The former name `employee_id` is still accepted for backwards compatibility; `staff_id` takes precedence if both are sent.

If your server submits leads on behalf of website visitors, send each visitor's `visitor_ip` and `visitor_user_agent`. Otherwise every lead carries your server's address, and spam filtering can flag them all as coming from one source.

**Required permission:** `lead_create`

## Headers

- `Api-Key` string, required

## Request body

- object
  - `first_name` string: Contact first name
  - `last_name` string: Contact last name
  - `email` string, required: Contact email address
  - `phone` string: Contact phone number
  - `company_name` string: Business or organization name
  - `staff_id` integer: Staff member ID requested for the lead's package
  - `lead_source` 'Manual Entry' | 'Lead Form' | 'Online Booking' | 'App' | 'Zapier' | 'API' | 'Wedding Wire': How the lead was acquired
  - `contact_preference` 'Email' | 'Phone' | 'Text Message': How the lead prefers to be contacted
  - `lead_type` string: Custom label for categorizing the lead
  - `notes` string: Private internal notes about this lead
  - `event_date` string: Requested event date (YYYY-MM-DD)
  - `event_time` string: Requested event start time
  - `length_in_minutes` integer: Requested event duration in minutes
  - `estimated_budget` number: Estimated event budget
  - `estimated_number_guests` integer: Estimated number of guests
  - `venue_name` string: Event venue name
  - `venue_address` string: Venue street address
  - `venue_city` string: Venue city
  - `venue_state` string: Venue state
  - `venue_zip` string: Venue ZIP code
  - `indoor_outdoor` 'Indoor' | 'Outdoor': Venue type
  - `service_id` integer: Service (event category) ID the lead is interested in, from `GET /api/v1/event_categories`. Ignored when `package_id` is sent: the package sets the service. Must belong to this business.
  - `package_id` integer: Package (event type) ID the lead is interested in, from `GET /api/v1/packages`. Must belong to this business.
  - `referred_by_user_id` integer: ID of the staff member who referred this lead
  - `next_follow_up_on` string: Next follow-up date (YYYY-MM-DD)
  - `subject` string: Message subject from the lead inquiry
  - `message` string: Message body from the lead inquiry
  - `utm_source` string: UTM source tracking parameter
  - `utm_campaign` string: UTM campaign tracking parameter
  - `utm_medium` string: UTM medium tracking parameter
  - `utm_term` string: UTM term tracking parameter
  - `utm_content` string: UTM content tracking parameter
  - `gclid` string: Google Click ID for ad tracking
  - `visitor_ip` string: IP address (IPv4 or IPv6) of the website visitor who submitted the inquiry. Send this when your server creates leads on a visitor's behalf so spam filtering checks the visitor rather than your server.
  - `visitor_user_agent` string: Browser user agent of the website visitor who submitted the inquiry. Send this alongside `visitor_ip`.
  - `custom_questions` object: Responses to custom booking questions configured by the business, as key-value pairs

## Response `200`

lead created

---

[API](https://skmtc.dev/checkcherry/apis/check-cherry-business-api.md) · [All operations](https://skmtc.dev/checkcherry/apis/check-cherry-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/checkcherry/apis/check-cherry-business-api/revisions/84a9aabdf519?raw)