API

API reference

Every endpoint, with parameters, example requests and responses.

All endpoints require an API key. See API introduction for authentication, scopes, pagination and error handling.

List leads

GET/api/v1/leadsscope: read:leads

Returns your company's leads, newest first, one page at a time.

Query parameters

Name	Type	Description
`limit`	`integer`	Page size. Default 25, maximum 100.
`cursor`	`string`	The `nextCursor` value from the previous page. Omit for the first page.

Example request

curl "https://YOUR-DOMAIN/api/v1/leads?limit=25" \
  -H "Authorization: Bearer vdb_live_YOUR_KEY"

Responses

200A page of leads.

Field	Type	Description
`id`	`string`
`status`	`string`	A value from your company's lead stages (e.g. `NEW`, `CONTACTED`, `QUOTE_SENT`). Stages are configurable in Settings → Custom Lists.
`firstName`	`string`
`lastName`	`string`
`email`	`string \| null`
`phone`	`string \| null`
`eventType`	`string \| null`	A value from your Event Types list, e.g. `wedding`.
`eventDate`	`string (date-time) \| null`
`guestCount`	`integer \| null`
`source`	`string \| null`	e.g. `web_form`, `referral`, `api`.
`createdAt`	`string (date-time)`

{
  "data": [
    {
      "id": "cm1x9k2…",
      "status": "NEW",
      "firstName": "Jordan",
      "lastName": "Blake",
      "email": "jordan.blake@example.com",
      "phone": "843-555-0142",
      "eventType": "wedding",
      "eventDate": "2027-05-15T21:00:00.000Z",
      "guestCount": 140,
      "source": "web_form",
      "createdAt": "2026-10-06T14:02:11.000Z"
    }
  ],
  "nextCursor": "cm1x9k2…"
}

401Missing, invalid, revoked or expired API key.

{
  "error": "Invalid or expired API key"
}

403The key does not have the `read:leads` scope.

{
  "error": "API key is missing scope: read:leads"
}

429Rate limit exceeded (100 requests per minute per key).

{
  "error": "Rate limit exceeded"
}

Create a lead

POST/api/v1/leadsscope: write:leads

Creates a lead in your company's first active pipeline stage and records it in the lead's history. The lead's source is set to `api`. Note: this does not fire the `lead.created` webhook.

Request body application/json

Field	Type	Description
`firstName` required	`string`	Required.
`lastName` required	`string`	Required.
`email`	`string (email)`
`phone`	`string`
`eventDate`	`string (date-time)`	ISO 8601 with a time zone, e.g. `2027-05-15T21:00:00Z`.
`eventType`	`string`	Free text; use one of your Event Types values (e.g. `wedding`) so it filters and reports correctly.
`guestCount`	`integer`	Positive whole number.
`notes`	`string`

Example request

curl -X POST "https://YOUR-DOMAIN/api/v1/leads" \
  -H "Authorization: Bearer vdb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jordan","lastName":"Blake","email":"jordan.blake@example.com","phone":"843-555-0142","eventType":"wedding","eventDate":"2027-05-15T21:00:00Z","guestCount":140,"notes":"Found us through the website form."}'

Responses

201The lead was created.

Field	Type	Description
`data`	`object`

400The body is not valid JSON or fails validation. `details` lists the offending fields.

{
  "error": "Invalid request body",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "email": [
        "Invalid email"
      ]
    }
  }
}

401Missing, invalid, revoked or expired API key.

{
  "error": "Invalid or expired API key"
}

403The key does not have the `write:leads` scope.

{
  "error": "API key is missing scope: write:leads"
}

429Rate limit exceeded (100 requests per minute per key).

{
  "error": "Rate limit exceeded"
}

List events

GET/api/v1/eventsscope: read:events

Returns your company's events ordered by event date, latest first, one page at a time. Time, room and guest count come from the event's first function.

Query parameters

Name	Type	Description
`limit`	`integer`	Page size. Default 25, maximum 100.
`cursor`	`string`	The `nextCursor` value from the previous page. Omit for the first page.

Example request

curl "https://YOUR-DOMAIN/api/v1/events?limit=25" \
  -H "Authorization: Bearer vdb_live_YOUR_KEY"

Responses

200A page of events.

Field	Type	Description
`id`	`string`
`status`	`"INQUIRY" \| "HOLD" \| "TENTATIVE" \| "CONFIRMED" \| "COMPLETED" \| "CANCELED" \| "NO_SHOW"`
`eventName`	`string \| null`
`eventType`	`string \| null`
`eventDate`	`string (date-time)`	Start of the event's earliest function.
`venueId`	`string`
`clientId`	`string \| null`
`createdAt`	`string (date-time)`
`startTime`	`string (date-time) \| null`	First function's start.
`endTime`	`string (date-time) \| null`	First function's end.
`eventSpaceId`	`string \| null`	First function's primary room.
`eventSpaceIds`	`string[]`	Every room the first function is booked into (primary room first).
`guestCount`	`integer \| null`	First function's guest count, falling back to the event's estimate.

{
  "data": [
    {
      "id": "ev_0042",
      "status": "CONFIRMED",
      "eventName": "Bennett–Sutton Wedding",
      "eventType": "wedding",
      "eventDate": "2027-05-15T21:30:00.000Z",
      "venueId": "cm1…",
      "clientId": "cl_0042",
      "createdAt": "2026-02-03T15:20:00.000Z",
      "startTime": "2027-05-15T21:30:00.000Z",
      "endTime": "2027-05-16T03:00:00.000Z",
      "eventSpaceId": "cm1…",
      "guestCount": 220
    }
  ],
  "nextCursor": null
}

401Missing, invalid, revoked or expired API key.

{
  "error": "Invalid or expired API key"
}

403The key does not have the `read:events` scope.

{
  "error": "API key is missing scope: read:events"
}

429Rate limit exceeded (100 requests per minute per key).

{
  "error": "Rate limit exceeded"
}

Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1) — import it into Postman, Insomnia or a client generator.

API reference

#List leads

Query parameters

Example request

Responses

#Create a lead

Request body application/json

Example request

Responses

#List events

Query parameters

Example request

Responses

List leads

Create a lead

List events