The Leads API allows you to build a fully-custom contact form to capture leads in Perfect Venue. Unlike our embedded contact form solution, the Leads API gives you full control over the style and experience of your contact form. It also allows for better integration with analytics tools you may be using to track referrals.
This article describes how to build a custom contact form from scratch using HTML and JavaScript. For more specific instructions based on your website's platform, see additional information below.
Before You Start
The Leads API requires an Enterprise plan. If you are on the Enterprise plan, you should see the Settings > API option under your venue settings.
API Keys
The Leads API uses a public API key to identify the venue to receive the lead. Every request must include your API key in the X-Public-API-Token header.
X-Public-API-Token: pk_your_api_key_here
Allowed Origins
All requests must come from an origin (i.e. your company’s website URL) that is allow-listed in your venue settings. Add the URL of your website under Settings > API > Allowed Origins before going live.
.png?width=670&height=263&name=image%20(2).png)
Submitting a Lead
Request
POST /public/v1/leads
Content-Type: application/json
X-Public-API-Token: pk_your_api_key_here
Payload example:
{
"event": {
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"phone": "555-555-5555",
"account": "Acme Corp",
"message": "We are looking for a venue for our annual company dinner.",
"event_name": "Annual Dinner",
"event_type": "Corporate",
"group_size": 80,
"budget": 15000,
"start_date": "2026-09-15",
"end_date": "2026-09-15",
"start_time": "18:00",
"end_time": "22:00",
"spaces": ["d7sd797asgd8dh"]
},
"custom": {
"a1b2c3d4-...": "Google"
}
You can find more information about the lead schema in **Settings -> API -> Supported Fields**. This is also where you can find the IDs of your spaces and custom fields if you want to support those in your form.
Response
On success, the API returns HTTP 200:
{ "success": true }
The lead will appear in your Perfect Venue inbox as a new event with status **Lead**.
Complete Example
<form id="contact-form">
<input name="first_name" placeholder="First name" required />
<input name="last_name" placeholder="Last name" />
<input name="email" type="email" placeholder="Email" required />
<textarea name="message" placeholder="Tell us about your event" required></textarea>
<button type="submit">Send Inquiry</button>
</form>
<script>
document.getElementById('contact-form').addEventListener('submit', async (e) => {
e.preventDefault();
const PUBLIC_KEY = 'replace-with-your-public-api-key';
const form = new FormData(e.target);
const res = await fetch('https://api.perfectvenue.com/public/v1/leads', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Public-API-Token': PUBLIC_KEY,
},
body: JSON.stringify({
event: {
first_name: form.get('first_name'),
last_name: form.get('last_name'),
email: form.get('email'),
message: form.get('message'),
},
}),
});
if (res.ok) {
alert('Thanks! We will be in touch soon.');
} else {
const data = await res.json();
alert('Something went wrong: ' + data.detail);
}
});
</script>
FAQ
Does the Lead Form API support custom fields?
Yes, the Lead Form API supports custom fields. You can provide custom fields by adding a custom object to the payload. The custom object should have keys that are the IDs of your custom fields.
const payload = {
event: {
first_name: "Henry",
email: "henry@perfectvenue.com",
message: "Will you please host my event?",
},
custom: {
"8e37e214-3281-4af9-b054-bcd7e581c88a": "555 Main Street, San Francisco, CA 94111"
}
};
You can find your venue’s custom field IDs on the API settings page.
Do my contact form settings impact the Lead Form API?
The Lead Form API does not regard the required/optional settings on custom fields. If you want to make a custom field required, you can add whatever validations you would like to your custom web form.
The Lead Form API does consider the types of custom fields, i.e. if the custom field is a multiple-choice selection, you must provide an array of values in the request.
How do I implement a group contact form?
If you want to create one form that can create leads in multiple venues, simply get the public API keys for each venue you'd like to target and allow the guest to select one via an HTML select. Note that, only venues on the Enterprise plan are able to use the Lead Form API.
How do I implement Google Analytics?
There is no special integration for Google Analytics, now that the contact form is implemented on your website. Simply follow the docs for GA or whichever analytics platform you have chosen.