--- title: "Convert a lead to a booking" method: POST path: "/api/v1/leads/{lead_id}/convert_to_booking" tags: ["Leads"] --- # Convert a lead to a booking `POST /api/v1/leads/{lead_id}/convert_to_booking` ## Request - Base URL: `https://api.checkcherry.com` - URL: `https://api.checkcherry.com/api/v1/leads/{lead_id}/convert_to_booking` - Auth: none declared. Required headers: `Api-Key` Converts a lead into a booking -- an event the client has already committed to. For one they still have to accept, use `POST /api/v1/leads/{lead_id}/convert_to_proposal`. 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 booking. Send an empty body to take all of it as-is. **Every field below is optional**, and overrides what came from the lead. `signature_collected` defaults to `true`, which creates the booking `confirmed`. Send `false` when you are still waiting on the contract and it is created `awaiting_signature` instead. ### Packages `packages` **replaces** the lead's packages outright rather than merging with them. Leave it out to book 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/bookings`. ### 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` ## Path parameters - `lead_id` integer, required ## Headers - `Api-Key` string, required ## Request body - object - `signature_collected` boolean: Has the signature already been collected? Defaults to `true`, creating a `confirmed` booking. `false` creates it `awaiting_signature`. - `send_contact_invitation_to_create_account` boolean: Email the client an invitation to create an account. Requires an email on the lead or in `contact_email`. - `send_booking_confirmation_emails` boolean: Send the client the booking confirmation emails. Requires an email on the lead or in `contact_email`. - `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_id` integer: The existing client's user ID, which must belong to this business. Required when `contact_type` is `Existing Customer`. - `contact_name` string: Client's name. Overrides the lead's. - `contact_email` string: Client's email. Overrides the lead's. - `contact_phone` string: Client's phone - `contact_company_name` string: Client's company name - `contact_description` string: Client's role, e.g. "Bride" or "Father of the Groom" - `contact_street` string: Client's street address - `contact_city` string: Client's city - `contact_state_code` string: Client's state or province code, in whatever form the business's country uses, e.g. `MA` - `contact_postal_code` string: Client's postal code - `venue_name` string: Venue name. Overrides the lead's. - `venue_address` string: Venue street address - `venue_city` string: Venue city - `venue_state` string: Venue state or province code, in whatever form the business's country uses, e.g. `MA` - `venue_zip` string: Venue postal code - `venue_google_place_id` string: Google Place ID for the venue - `venue_latitude` number: Venue latitude - `venue_longitude` number: Venue longitude - `add_tax` boolean: Apply tax based on the venue's tax zone. Defaults to `true`. - `add_travel` boolean: Apply travel fees based on the venue's travel zone. Defaults to `true`. - `public_notes` string: Notes visible to the client - `private_notes` string: Notes only staff can see. Defaults to the lead's notes. - `custom_title` string: Overrides the generated title - `brand_id` integer: Brand to book under, which must be an active brand of this business. Defaults to the lead's brand. - `total_amount` number: Overrides the calculated event total. In whole currency units, so `1250.00` means $1,250.00. Max 999000. - `paid_amount` number: Payment already collected outside Check Cherry, recorded against the event. In whole currency units. Max 999000. - `custom_deposit_amount` number: Overrides the calculated deposit due. In whole currency units, and capped at the event total. Max 999000. - `packages` object[]: Replaces the packages carried over from the lead. Leave it out to keep them. - `event_type_id` string, required: Package ID, from `GET /api/v1/packages`. Send the literal `custom` to price a one-off package instead, alongside `one_off_custom_title` and `total_amount`. - `starts_at_date` string, required: Start date, as ISO `YYYY-MM-DD`. Other numeric formats are read according to the business's date format setting. - `starts_at_time` string: Start time, e.g. `11:00AM`, `2:30pm` or `14:30`. Required for packages scheduled by date and time. - `ends_at_time` string: Overrides the end time implied by the length. Same formats as `starts_at_time`. - `length_in_minutes` integer: Length in minutes, from 1 to 1440. Required for packages that let extra hours be booked, otherwise defaults to the package's own length. - `length_in_days` integer: Length in days, from 1 to 1000. Required for packages that let extra days be booked. - `units` integer: Unit count, for packages priced per unit. Must fall inside one of that package's unit ranges, which are listed on `GET /api/v1/packages/{id}`. - `package_unit_range_id` integer: Unit range ID, for packages priced by unit range. Must be one of that package's own ranges, from `GET /api/v1/packages/{id}`. - `backdrop_id` integer: Backdrop ID, from `GET /api/v1/photobooth_backgrounds` - `add_on_ids` string: Comma-separated add-on IDs, e.g. `4,17`. Prefix an ID with a quantity to book more than one: `2x17`. - `staff_id` integer: Staff member assigned to this package, who must belong to this business. Ignored when the package's service assigns staff automatically. - `one_off_custom_title` string: Title for a one-off package. Required when `event_type_id` is `custom`. - `custom_description_html` string: Description for a one-off package ## Response `200` lead converted to a booking --- [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)