Available with any of the following subscriptions:
✓ Ultimate
Retrieve events within a date range, or retrieve a single event by its ID. Optionally include related client, location, services, financial totals, invoices and quotes. Event-list requests support pagination.
You will need to contact support to have the API enabled for your account.
List events: GET https://management.bandpencil.com/api/v1/public/events
Get one event: GET https://management.bandpencil.com/api/v1/public/events/{event_id}
Auth: X-API-Key:
Success: 200 OK
Content type: application/json
Generate keys in Band Pencil → Settings → API. We will automatically assign your API key a unique name. Copy the key somewhere secure alongside the unique name, as you won't be able to view the API key again.
You'll see the key name in your audit logs so you know which integration created or accessed your data.
Send the following header with every request:
X-API-Key: YOUR_API_KEY
If the API key is missing or invalid you'll receive a 401 or 403 response.
Use the following query parameters with GET /events:
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from |
date (YYYY-MM-DD) |
Yes | Start of the date range. |
date_to |
date (YYYY-MM-DD) |
Yes | End of the date range. There is a maximum of 1 year date range. |
page |
integer | No | Page number to return. Defaults to 1. |
per_page |
integer | No | Number of events per page. Defaults to 50, with a maximum of 100. |
include |
string | No | Comma-separated list of additional related data to include. |
For GET /events/{event_id}, date_from, date_to, page and per_page are not required. You can still use the optional include parameter.
The following values may be supplied to the include parameter:
| Value | Description |
client |
Include client information. |
location |
Include location information. |
services |
Include assigned services. |
finances |
Include event-level invoice totals. |
invoices |
Include invoices and their line items. |
quotes |
Include quotes and their line items. |
Multiple values can be combined, for example:
include=client,location,services,finances,invoices,quotes
The include parameter is optional. Omitting it returns only the core event information.
curl "https://management.bandpencil.com/api/v1/public/events?date_from=2026-05-01&date_to=2026-05-31" \
-H "X-API-Key: YOUR_API_KEY"
curl "https://management.bandpencil.com/api/v1/public/events?date_from=2026-05-01&date_to=2026-05-31&page=2&per_page=25" \
-H "X-API-Key: YOUR_API_KEY"
curl "https://management.bandpencil.com/api/v1/public/events/e12345678" \
-H "X-API-Key: YOUR_API_KEY"
curl "https://management.bandpencil.com/api/v1/public/events/e12345678?include=client,location,services,finances,invoices,quotes" \
-H "X-API-Key: YOUR_API_KEY"
curl "https://management.bandpencil.com/api/v1/public/events?date_from=2026-05-01&date_to=2026-05-31&include=client,location,services,finances,invoices,quotes" \
-H "X-API-Key: YOUR_API_KEY"
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://management.bandpencil.com'
]);
$response = $client->get('/api/v1/public/events', [
'headers' => [
'X-API-Key' => $_ENV['BAND_PENCIL_API_KEY']
],
'query' => [
'date_from' => '2026-05-01',
'date_to' => '2026-05-31',
'include' => 'client,location,invoices,quotes'
]
]);
$data = json_decode($response->getBody()->getContents(), true);
{
"status": "Success",
"data": {
"events": [
{
"event_id": "e12345678",
"name": "Wedding - Smiths",
"date": "2026-05-18",
"multiple_days": false,
"date_end": null,
"time_start": "18:00",
"time_end": "23:00",
"all_day": false,
"status": "Confirmed",
"location_id": "lo123456",
"client_id": "cl123456",
"referral_id": "rs123456",
"description": "Evening wedding reception.",
"private_notes": "Client prefers acoustic set.",
"timings_breakdown": "Arrival 17:00\nSoundcheck 17:30",
"setup_breakdown": "2x powered speakers",
"food_provided": "Hot meal for 4",
"noise_limit": "92 dB",
"number_of_guests": "120",
"mileage": "18",
"green_room": "Yes",
"performance_room": "Great Barn",
"created_at": "2026-02-01 12:15:44",
"resource_url": "https://management.bandpencil.com/event/e12345678",
"client": {
"client_id": "cl123456",
"name": "John Smith",
"company": "Smith Events",
"phone": "07123456789",
"email": "john@example.com"
},
"location": {
"location_id": "lo123456",
"name": "Healey Barn",
"address": "Riding Mill, Northumberland",
"google_verified_location": true
},
"services": [
{
"service_id": "b123456",
"name": "Evening Performance",
"notes": "",
"private_notes": ""
}
],
"finances": {
"invoice_subtotal": "1200.00",
"invoice_tax_total": "240.00",
"invoice_total": "1440.00"
},
"invoices": [
{
"invoice_id": "i123456",
"display_id": "INV-1001",
"name": "Final Invoice",
"purchase_order": null,
"issue_date": "2026-05-01",
"due_date": "2026-05-15",
"notes": "",
"subtotal": "1200.00",
"tax_total": "240.00",
"total": "1440.00",
"paid": false,
"sent": true,
"visible": true,
"pay_online": true,
"integration": null,
"integration_sent": null,
"integration_id": null,
"items": [
{
"item_id": 123,
"name": "Evening Performance",
"description": "5-piece band",
"amount": "1200.00",
"tax_rate": "20.00",
"tax_total": "240.00",
"total": "1440.00",
"position": 1,
"due_date": "2026-05-15"
}
]
}
],
"quotes": [
{
"quote_id": "q123456",
"display_id": "QUO-1001",
"name": "Wedding Quote",
"issue_date": "2026-04-01",
"expiry_date": "2026-04-30",
"notes": "",
"subtotal": "1200.00",
"tax_total": "240.00",
"total": "1440.00",
"accepted": true,
"client_acceptance": "yes",
"sent": true,
"visible": true,
"items": [
{
"item_id": 124,
"name": "Evening Performance",
"description": "5-piece band",
"amount": "1200.00",
"tax_rate": "20.00",
"tax_total": "240.00",
"total": "1440.00",
"position": 1,
"due_date": null,
"required": false,
"accepted": false
}
]
}
]
}
],
"count": 1
},
"pagination": {
"page": 1,
"per_page": 50,
"total": 1,
"total_pages": 1,
"has_more": false
},
"filters": {
"date_from": "2026-05-01",
"date_to": "2026-05-31",
"include": [
"client",
"location",
"services",
"finances",
"invoices",
"quotes"
]
},
"version": "1.0"
}
A successful GET /events/{event_id} request returns the event under data.event rather than data.events. Pagination and date filters are not returned for single-event requests.
{
"status": "Success",
"data": {
"event": {
"event_id": "e12345678",
"name": "Wedding - Smiths",
"date": "2026-05-18",
"multiple_days": false,
"date_end": null,
"time_start": "18:00",
"time_end": "23:00",
"all_day": false,
"status": "Confirmed",
"location_id": "lo123456",
"client_id": "cl123456",
"referral_id": "rs123456",
"description": "Evening wedding reception.",
"private_notes": "Client prefers acoustic set.",
"timings_breakdown": "Arrival 17:00\nSoundcheck 17:30",
"setup_breakdown": "2x powered speakers",
"food_provided": "Hot meal for 4",
"noise_limit": "92 dB",
"number_of_guests": "120",
"mileage": "18",
"green_room": "Yes",
"performance_room": "Great Barn",
"created_at": "2026-02-01 12:15:44",
"resource_url": "https://management.bandpencil.com/event/e12345678"
}
},
"include": [],
"version": "1.0"
}
Every event includes the following fields:
| Field | Description |
event_id |
Unique event identifier. |
name |
Event name. |
date |
Event start date. |
multiple_days |
Whether the event spans multiple days. |
date_end |
Event end date, if applicable. |
time_start |
Event start time, or null for all-day events. |
time_end |
Event end time, or null for all-day events. |
all_day |
Indicates whether the event is an all-day event. |
status |
Current event status. |
location_id |
Linked location ID, if assigned. |
client_id |
Linked client ID, if assigned. |
referral_id |
Linked referral ID, if assigned. |
description |
Public event description. |
private_notes |
Private event notes. |
timings_breakdown |
Running order and timings. |
setup_breakdown |
Equipment and setup notes. |
food_provided |
Catering information. |
noise_limit |
Noise restriction details. |
number_of_guests |
Guest count. |
mileage |
Mileage information. |
green_room |
Green room information. |
performance_room |
Performance location. |
created_at |
Date the event was created. |
resource_url |
Direct link to the event within Band Pencil. |
List responses include a pagination object:
| Field | Description |
page |
Current page number. |
per_page |
Number of events requested per page. |
total |
Total number of matching events across all pages. |
total_pages |
Total number of available pages. Returns 0 when there are no matching events. |
has_more |
true when another page of results is available. |
The response data.count is the number of events returned on the current page, while pagination.total is the total number of matching events.
When include=invoices is supplied, each event includes an invoices array.
Each invoice may contain:
| Field | Description |
invoice_id |
Unique invoice identifier. |
display_id |
User-facing invoice number, if set. |
name |
Invoice name. |
purchase_order |
Purchase order/reference, if set. |
issue_date |
Invoice issue date. |
due_date |
Invoice due date. |
notes |
Invoice notes. |
subtotal |
Invoice subtotal before tax. |
tax_total |
Total tax charged. |
total |
Total invoice value including tax. |
paid |
Whether the invoice is marked as paid. |
sent |
Whether the invoice is marked as sent. |
visible |
Whether the invoice is visible to the client. |
pay_online |
Whether online payment is enabled. |
integration |
External accounting integration, if applicable. |
integration_sent |
Date/time the invoice was sent to the integration. |
integration_id |
External invoice identifier returned by the integration. |
items |
Invoice line items. |
Each invoice item contains its name, description, amount, tax rate, tax total, total value, position and due date.
When include=quotes is supplied, each event includes a quotes array.
Each quote may contain:
| Field | Description |
quote_id |
Unique quote identifier. |
display_id |
User-facing quote number, if set. |
name |
Quote name. |
issue_date |
Quote issue date. |
expiry_date |
Quote expiry date. |
notes |
Quote notes. |
subtotal |
Quote subtotal before tax. |
tax_total |
Total tax quoted. |
total |
Total quoted value including tax. |
accepted |
Whether the quote has been accepted. |
client_acceptance |
Client acceptance mode, such as yes, options or no. |
sent |
Whether the quote is marked as sent. |
visible |
Whether the quote is visible to the client. |
items |
Quote line items. |
Quote line items also contain required and accepted values where relevant. These are particularly useful when a quote allows the client to choose between optional services.
| HTTP status | Status | Meaning |
| 401 | AuthError |
Missing API key. |
| 403 | AuthError |
Invalid or inactive API key. |
| 403 | NotAllowed |
Your plan does not include API access. |
| 404 | NotFound |
The requested event ID could not be found. |
| 422 | MissingFields |
date_from or date_to is missing or invalid on a list request. |
| 422 | ValidationError |
date_to is before date_from, or an unsupported include value was supplied. |
| 500 | Failure |
Internal server error. |
page defaults to 1; per_page defaults to 50 and is capped at 100.include parameter is optional for both list and single-event requests. Omitting it returns only the core event information.GET /events/{event_id} without supplying a date range."invoices": [].include parameter return a 422 ValidationError response.