Leads

Convert a lead to a proposal

Converts a lead into a proposal -- an event the client still has to accept. For one they have already committed to, use POST /api/v1/leads/{lead_id}/convert_to_booking.

The lead's own details are filled in for you. Its packages, venue, notes, brand and client all carry over, along with its source, guest count, budget and campaign attribution. The lead is marked converted and its message history moves onto the new proposal. Send an empty body to take all of it as-is.

Every field below is optional, and overrides what came from the lead.

proposal_date_reserved decides whether the date is held. It defaults to false, which leaves the date open to other bookings until the client accepts.

Packages

packages replaces the lead's packages outright rather than merging with them. Leave it out to propose exactly what the lead asked for. Each entry you do send needs an event_type_id (a package id from GET /api/v1/packages) and a starts_at_date.

Pricing, tax, travel fees and the title are all calculated from the packages and the venue. Send total_amount only to override the calculated total.

Attaching the client

The lead's contact details become the client, and when the lead's email matches somebody the business already has, that person is linked rather than duplicated. Send contact_type and the contact_* fields to attach someone else instead -- they work exactly as they do on POST /api/v1/proposals.

Converting more than once

A lead that has already been converted converts again, producing a second event and leaving the first alone. Check converted_to_event on the lead first if that isn't what you want.

Dates, times and amounts

Dates are ISO YYYY-MM-DD. Other numeric formats are read according to the business's own date format setting, so 03-04-2027 is March 4th for a US business and April 3rd for an international one. Times take 11:00AM, 2:30pm or 14:30.

Amounts are in the business's currency in whole units rather than cents, so 1250.00 is $1,250.00.

Required permission: event_create or proposal_create

post/api/v1/leads/{lead_id}/convert_to_proposal

Request

  • Base URL: https://api.checkcherry.com
  • URL: https://api.checkcherry.com/api/v1/leads/{lead_id}/convert_to_proposal
  • Auth: none declared. Required headers: Api-Key

Path parameters

lead_idinteger required

The unique ID of the lead

Headers

Api-Keystring required

Your Integration Key

Request body

proposal_date_reservedboolean

Hold the date for the client while they decide. Defaults to false, leaving it open to other bookings.

proposal_valid_throughstring

Last day the client can accept, as ISO YYYY-MM-DD. Defaults to the business's own proposal expiry setting, and cannot fall after the event date.

contact_type'New Customer' | 'Existing Customer' | 'None'

Where the client comes from. Defaults to the lead's own contact details. Existing Customer needs customer_user_id; New Customer builds one from the contact_* fields; None attaches nobody.

customer_user_idinteger

The existing client's user ID, which must belong to this business. Required when contact_type is Existing Customer.

contact_namestring

Client's name. Overrides the lead's.

contact_emailstring

Client's email. Overrides the lead's.

contact_phonestring

Client's phone

contact_company_namestring

Client's company name

contact_descriptionstring

Client's role, e.g. "Bride" or "Father of the Groom"

contact_streetstring

Client's street address

contact_citystring

Client's city

contact_state_codestring

Client's state or province code, in whatever form the business's country uses, e.g. MA

contact_postal_codestring

Client's postal code

venue_namestring

Venue name. Overrides the lead's.

venue_addressstring

Venue street address

venue_citystring

Venue city

venue_statestring

Venue state or province code, in whatever form the business's country uses, e.g. MA

venue_zipstring

Venue postal code

venue_google_place_idstring

Google Place ID for the venue

venue_latitudenumber

Venue latitude

venue_longitudenumber

Venue longitude

add_taxboolean

Apply tax based on the venue's tax zone. Defaults to true.

add_travelboolean

Apply travel fees based on the venue's travel zone. Defaults to true.

public_notesstring

Notes visible to the client

private_notesstring

Notes only staff can see. Defaults to the lead's notes.

custom_titlestring

Overrides the generated title

brand_idinteger

Brand to book under, which must be an active brand of this business. Defaults to the lead's brand.

total_amountnumber

Overrides the calculated event total. In whole currency units, so 1250.00 means $1,250.00. Max 999000.

paid_amountnumber

Payment already collected outside Check Cherry, recorded against the event. In whole currency units. Max 999000.

custom_deposit_amountnumber

Overrides the calculated deposit due. In whole currency units, and capped at the event total. Max 999000.

Response

lead converted to a proposal

Changes

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