Using the API to get events

Subscription availability

Available with 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.

At a glance

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

Getting your API key

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.

Authentication & headers

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.

Query parameters

List events

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.

Get a single event

For GET /events/{event_id}, date_from, date_to, page and per_page are not required. You can still use the optional include parameter.

Include options

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.

Example requests

Basic request

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"

Paginated request

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"

Get a single event

curl "https://management.bandpencil.com/api/v1/public/events/e12345678" \
  -H "X-API-Key: YOUR_API_KEY"

Get a single event with related data

curl "https://management.bandpencil.com/api/v1/public/events/e12345678?include=client,location,services,finances,invoices,quotes" \
  -H "X-API-Key: YOUR_API_KEY"

Including related data

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"

PHP (Guzzle)

$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);

Example response

{
  "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"
}

Single event response

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"
}

Response fields

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.

Pagination

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.

Included invoices

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.

Included quotes

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.

Error responses

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.

Notes

List responses are paginated. page defaults to 1; per_page defaults to 50 and is capped at 100.
Events are returned ordered by event date, then start time, then creation order.
Multi-day events are returned if any part of the event falls within the requested date range.
The include parameter is optional for both list and single-event requests. Omitting it returns only the core event information.
A single event can be retrieved with GET /events/{event_id} without supplying a date range.
Invoices and quotes include their associated line items when requested.
Empty related collections are returned as empty arrays, for example "invoices": [].
Unsupported values supplied to the include parameter return a 422 ValidationError response.

Was this article helpful?

Using the API to get events

At a glance

Getting your API key

Authentication & headers

Query parameters

List events

Get a single event

Include options

Example requests

Basic request

Paginated request

Get a single event

Get a single event with related data

Including related data

PHP (Guzzle)

Example response

Single event response

Response fields

Pagination

Included invoices

Included quotes

Error responses

Notes

Start with Band Pencil now.