API introduction

The VenueDB API lets your own tools read your leads and events and create new leads — for example, to send website form submissions straight into your pipeline.

• Base URL: https://YOUR-DOMAIN/api/v1
• Format: JSON requests and responses
• Auth: an API key sent as a Bearer token
• Scope: every key belongs to one company and can only see that company's data

The full list of endpoints is in the API reference. A machine-readable OpenAPI 3.1 file is available at /api/v1/openapi.json.

#Create an API key

1. Sign in as the owner of the company.
2. Go to Settings → API and create a key. Give it a name that says what uses it (for example "Website contact form").
3. Choose the scopes it needs. Grant as little as possible.
4. Copy the key immediately. It is shown only once; VenueDB stores a hash, not the key.

Keys start with vdb_live_. A key works until you revoke it, which you can do at any time from the same page.

#Authenticate

Send the key in the Authorization header:

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

#Scopes

A request without the right scope returns 403.

#Pagination

List endpoints return one page at a time, using a cursor:

• limit — page size, default 25, maximum 100.
• cursor — pass the nextCursor from the previous response to get the next page.

{
  "data": [ /* … */ ],
  "nextCursor": "cm1x9k2abc"
}

When nextCursor is null, you have reached the end.

#Errors

Errors always come back as JSON with an error message:

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

#Rate limits

Each key may make 100 requests per minute. When you exceed that you get 429; wait for the window to reset and retry. For bulk work, use the largest limit (100) rather than many small requests.

#Dates and IDs

• Dates and times are ISO 8601 in UTC, for example 2027-05-15T21:00:00.000Z. When sending a date, include a time zone (Z or an offset).
• IDs are opaque strings. Store them as-is and don't assume a format.

#Real-time updates

To be told when something happens instead of polling, use webhooks.

#Seeing what's failing

VenueDB records failed API requests — a missing or revoked key, a missing scope, an invalid body or a server error — against the key that made them, with the reason, for 14 days. If a key is being used and a large share of its requests fail, a problem appears under Dashboard → Background jobs → Connections (and you're notified once), for example:

API key — Website form: 12 of 12 requests failed in the last day (403: API key is missing scope: read:leads).

That is usually the quickest way to spot a form on your website that has stopped working. Successful requests aren't logged individually; VenueDB keeps a daily count per key.