Leads

Add a lead to the database

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

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

Headers

Api-Keystring required

Your Integration Key

Request body

first_namestring

Contact first name

last_namestring

Contact last name

emailstring required

Contact email address

phonestring

Contact phone number

company_namestring

Business or organization name

staff_idinteger

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_typestring

Custom label for categorizing the lead

notesstring

Private internal notes about this lead

event_datestring

Requested event date (YYYY-MM-DD)

event_timestring

Requested event start time

length_in_minutesinteger

Requested event duration in minutes

estimated_budgetnumber

Estimated event budget

estimated_number_guestsinteger

Estimated number of guests

venue_namestring

Event venue name

venue_addressstring

Venue street address

venue_citystring

Venue city

venue_statestring

Venue state

venue_zipstring

Venue ZIP code

indoor_outdoor'Indoor' | 'Outdoor'

Venue type

service_idinteger

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_idinteger

Package (event type) ID the lead is interested in, from GET /api/v1/packages. Must belong to this business.

referred_by_user_idinteger

ID of the staff member who referred this lead

next_follow_up_onstring

Next follow-up date (YYYY-MM-DD)

subjectstring

Message subject from the lead inquiry

messagestring

Message body from the lead inquiry

utm_sourcestring

UTM source tracking parameter

utm_campaignstring

UTM campaign tracking parameter

utm_mediumstring

UTM medium tracking parameter

utm_termstring

UTM term tracking parameter

utm_contentstring

UTM content tracking parameter

gclidstring

Google Click ID for ad tracking

visitor_ipstring

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_agentstring

Browser user agent of the website visitor who submitted the inquiry. Send this alongside visitor_ip.

custom_questionsobject

Responses to custom booking questions configured by the business, as key-value pairs

Response

lead created

Changes

No recorded changes to this operation across all 2 revisions of this API.