API - Leads - Create or Update

Create a new lead, or update an existing one, with a POST request to the Leads endpoint.

To update an existing lead, put the Lead ID in the URL, for example /api6/leads/234567, and send the fields you want to change. Any fields not sent will remain the same.

Note: updates use POST. A PUT request is refused with HTTP 405.

Request

All of the parameters below are optional except eventzip, which is required when creating a lead. This is not a complete list. Send the parameters as form fields or as a JSON body.

POST /api6/leads/?apiKey=YOUR_API_KEY {
  customerid: 533297
  locationid: 0
  eventname: Birthday Party
  eventstarttime: 1442003025
  eventendtime: 1442006025
  eventduration: 1.25
  eventstartdate_text: 7/25/2015
  eventstarttime_text: 2:00 pm
  eventenddate_text: 7/25/2015
  eventendtime_text: 4:00 pm
  eventstreet: 123 Happy St.
  eventcity: Harperville
  eventstate: OH
  eventzip: 44444
  eventcountry: United States
  taxexempt: No
  taxrate: 7.25
  salestax: 20.15
  status: Hold
  deliverytype: Drop-Off
  surface: Grass
  rental_names: Bounce House-1-125:Dora Panel-1-0|Slip & Slide-1-250
  rentals: 12345-1-125:12346-1-0|67890-1-250
  staffcost: 0
  distcharge: 0
  fee: 0
  adjust: 10.05
  coupon_code: FB Friend
  recalculate: 0
  notes: Has a rabid cat.
  additionalnotes1: test
  additionalnotes2: test2
  venuenotes: It's a park.
  venuename: Central Park
  venuecontact: Alex Kim
  guests: 100
  referral: Google Adwords
}

Parameters

Customer

Event Date and Time

Delivery and Return Times

These set the delivery (setup) and return (tear down) times shown on the lead's Contract tab and used by the delivery schedule and availability checks. Send only the ones you want to change.

Add save_time_fields with the value 1 to save these fields. Without it they are ignored and not checked, so requests that already include them keep working as before.

• Send null to clear a value (0 also clears the timestamps). An empty value is ignored.
• If a window half is blank, it is set to match the other half, the same as on the Contract tab. When moving a window that is already set, send both halves.
• With save_time_fields sent, times that do not fit the event return an HTTP 400 error and nothing on the lead is saved.
• If a lead is moved to a different date, its delivery and return windows are cleared unless new ones are sent in the same request.
• The values you send are always kept. On later requests, recalculate=1 recalculates setupduration, tdownduration and ttimefrom when your account calculates them automatically. Leave recalculate at 0 or send these values again to keep them.

Event Location and Details

Rentals

Use either rental_names or rentals to add rentals. Both use the same structure. rental_names identifies rentals and options by item name, while rentals identifies them by Rental ID.

rental_names: Item Name-Qty-Price:Option Name-Qty-Price|Next Item-Qty-Price
rentals:      12345-1-125:12346-1-0|67890-1-250

• Dashes separate the identifier, quantity, and price.
• Colons add options or accessories to the preceding rental.
• Bars separate additional rentals.
• Names sent through rental_names match without regard to upper or lower case or trailing spaces. If a name does not match an active item, the system creates a Quick Add item for it.
• A Rental ID sent through rentals that does not belong to your account, or to the lead's location, is skipped, together with the options sent with it.
• Only specify one of rental_names or rentals, not both. If both are sent, rental_names will be used.
• When updating a lead, the rentals you send replace all of the rentals already on the lead. Send the complete list, not only the change.

Add strict_rentals with the value 1 to reject rentals that are not found. With it, a name that does not match an active item (no Quick Add item is created) or a Rental ID that is not found, including one sent as an option, returns an HTTP 422 error that lists them, and the lead is not saved. Use it when your integration sends names or IDs from your own catalog, so a typo is reported instead of becoming a Quick Add item.

{
  "status": 422,
  "message": "Unknown rental(s): Bounce Huose"
}

Pricing

recalculate accepts these values:

• 0 (or not sent): the prices you send are kept, except fees set to auto-recalculate (in Promotions & Fees, or Distance, Staff, Surface and Delivery fees with auto-recalculate on in Optional Fields). Those are still recalculated, added if they apply, and removed if they no longer apply.
• 1: all prices, tax and fees are recalculated, overriding any prices you send. Fees added by hand on the lead are kept.
• 2: exactly what you send is saved and nothing is recalculated, including auto-recalculate fees. Only prices left blank are filled in.

When recalculate is 0 and you send a coupon_code, you must also send cpdiscount with the amount of the coupon discount. Otherwise it will be auto-calculated based on the promotion.

Default values specified in Settings > Optional Fields will be used if nothing is sent for that field.

Custom Fields

To fill in a lead custom field, send one parameter per field using the custom field ID:

customfield-35854: Blue balloons

You can find the IDs in the customfields_ids of a retrieved lead. See API - Leads - Retrieve Details.

You can also send custom fields in the same shapes a retrieved lead returns them. This makes it easy to read a lead, change a value, and send it back. All of these set the same field:

In a JSON body, send customfields or customfields_ids as an object:

{
  "apiKey": "YOUR_API_KEY",
  "customfields": {
    "Party Theme": "Blue balloons"
  }
}

• The name must match the custom field name in your account exactly.
• If the same field is sent more than one way, customfield-ID is used first, then customfields[Name], then customfields_ids[ID].
• Names and IDs that do not match a lead custom field in your account are ignored. No error is returned for them, so retrieve the lead afterwards if you need to confirm the value was saved.
• HTML tags are removed from the values.

Example

curl -X POST "https://rental.software/api6/leads" \
  -d "apiKey=YOUR_API_KEY" \
  -d "name=Jordan Rivera" \
  -d "email=jordan.rivera@example.com" \
  -d "eventname=Birthday Party" \
  -d "eventstartdate_text=7/25/2026" \
  -d "eventstarttime_text=2:00 pm" \
  -d "eventduration=2" \
  -d "eventzip=44444" \
  -d "rental_names=Bounce House-1-125"

Response

{
  "status": 201,
  "message": "Created",
  "recordid": 520248,
  "request_time": 1760000000
}

Add _body=true to the request to get the full saved lead back instead of the short response.

Errors

Deleting a Lead

Send a DELETE request with the Lead ID in the URL. The key needs Leads Full Access.

DELETE /api6/leads/234567?apiKey=YOUR_API_KEY

Related Links

• API - Leads - Retrieve Details
• API - Leads - Retrieve List
• API - Customers - Create or Update
• API - Create/Update Lead with Zapier
• API - Errors and Rate Limits