README

Official PHP SDK for the DJ Event Planner (DJEP) REST API.

Requirements

PHP 7.4 or later
cURL extension
JSON extension

Installation

Via Composer (recommended)

composer require djeventplannerhub/djep-php-sdk

Manual Installation

Download the SDK and include the autoloader:

require 'djep-php-sdk/autoload.php';

Quick Start

use DJEP\Client;

// Load your API key from environment variables (never hardcode keys)
$djep = new Client(getenv('DJEP_API_KEY'), getenv('DJEP_DOMAIN'));

// Check API status
$status = $djep->status();
echo $status->data->version;

// List upcoming events
$events = $djep->events->list(['status' => 'Booked', 'per_page' => 10]);
foreach ($events->data as $event) {
    echo $event->event_type . ' on ' . $event->event_date . "\n";
}

Authentication

Your API key is generated in DJEP under Setup > Integrations > API Key. The key format depends on your role:

Master Admin: secretkey_djidnumber
Employee/Salesperson: secretkey_djidnumber_employeeid

Important: Never hardcode your API key in source files. Use environment variables or a config file outside your web root.

// Option 1: Environment variable (recommended)
$djep = new Client(getenv('DJEP_API_KEY'), getenv('DJEP_DOMAIN'));

// Option 2: Config file outside web root
$config = require '/path/outside/webroot/djep-config.php';
$djep = new Client($config['api_key'], $config['domain']);

// Option 3: WordPress (wp-config.php constants)
$djep = new Client(DJEP_API_KEY, DJEP_DOMAIN);

Usage

Events

// List events
$events = $djep->events->list(['status' => 'Booked', 'sort_by' => 'event_date']);

// Get a single event
$event = $djep->events->get(56789);

// Create an event (financials auto-calculated from package)
$event = $djep->events->create([
    'clientid' => 12345,
    'event_date' => '2026-09-15',
    'event_type' => 'Wedding',
    'start_time' => '3:00 PM',
    'end_time' => '11:00 PM',
    'addons' => '501:2,502:1',
]);
echo "Total fee: " . $event->data->financials->total_fee;

// Update specific fields
$djep->events->update(56789, [
    'status' => 'Confirmed',
    'guest_count' => 200,
    'comments' => 'Client confirmed by phone',
]);

// Update and recalculate financials
$djep->events->update(56789, ['pkg_idnumber' => 14200], true);

// Delete an event (cascading)
$djep->events->delete(56789);

// Event sub-data
$payments = $djep->events->payments(56789);
$songs = $djep->events->musicRequests(56789);
$planning = $djep->events->planning(56789);

Clients

$clients = $djep->clients->list(['per_page' => 25]);
$client = $djep->clients->get(12345);

$newClient = $djep->clients->create([
    'first_name' => 'John',
    'last_name' => 'Smith',
    'email' => 'john@example.com',
]);

$djep->clients->update(12345, ['email' => 'new@example.com']);
$djep->clients->delete(12345);

Venues, Employees, Packages, Addons, Contacts

// All follow the same pattern
$venues = $djep->venues->list();
$venue = $djep->venues->get(789);

$employees = $djep->employees->list();
$packages = $djep->packages->list();
$addons = $djep->addons->list();
$contacts = $djep->contacts->list();

Vendors

$vendors = $djep->vendors->list();
$vendor = $djep->vendors->get(3456);

// Link a vendor to an event
$djep->vendors->linkToEvent(56789, 3456);

Payments

// List all payments company-wide
$payments = $djep->payments->list(['per_page' => 50]);

// Add a payment to an event
$result = $djep->payments->addToEvent(56789, 500.00, 'Credit Card', [
    'processing_fee' => 15.00,
    'comments' => 'Final payment',
]);
echo "Balance due: " . $result->data->balance_due;

Music Requests

// Get requests for an event
$songs = $djep->musicRequests->forEvent(56789);

// Add a music request
$djep->musicRequests->add(56789, 'Queen', 'Bohemian Rhapsody', 'MPL');
$djep->musicRequests->add(56789, 'ABBA', 'Dancing Queen', 'DED', 'For the bride');

Booking Helpers

// List available helpers
$helpers = $djep->bookingHelpers->list();

// Run a helper by unique_id (recommended)
$result = $djep->bookingHelpers->run(56789, 'book_event_1');
echo $result->data->log;

// Or by position index
$result = $djep->bookingHelpers->run(56789, null, 0);

Availability

// Check a single date
$avail = $djep->availability->check('09/15/2026');
if ($avail->data->available) {
    echo $avail->data->employees->available . ' employees available';
}

// Check a date range (max 90 days)
$range = $djep->availability->range('09/01/2026', '09/30/2026');
foreach ($range->data->dates as $date) {
    echo $date->date . ': ' . ($date->available ? 'Available' : 'Unavailable') . "\n";
}

Settings

// Website tools (form config, field labels, validation)
$rfiSettings = $djep->settings->websiteTools('request_info');

// Company settings
$company = $djep->settings->company();

// Custom field configuration
$fields = $djep->settings->customFields();

Expenses

$expenses = $djep->expenses->list(['per_page' => 25]);
$categories = $djep->expenses->categories();
$payees = $djep->expenses->payees();
$methods = $djep->expenses->paymentMethods();

Other Resources

// Submissions (read)
$rfi = $djep->submissions->rfi();
$quotes = $djep->submissions->quotes();
$contactUs = $djep->submissions->contactUs();

// Closed dates, equipment, systems
$closedDates = $djep->closedDates->list();
$equipment = $djep->equipment->list();
$systems = $djep->systems->list();

Create Submission (RFI)

Push leads from external sources into the DJ's submissions queue:

// Wedding Wire lead
$submission = $djep->submissions->create([
    'first_name' => 'Sarah',
    'last_name' => 'Johnson',
    'email' => 'sarah@example.com',
    'telephone' => '555-0123',
    'event_date' => '2026-09-15',
    'event_type' => 'Wedding',
    'guest_count' => 200,
    'source' => 'Wedding Wire',
    'send_notification' => 'true',
]);
echo "Submission ID: " . $submission->data->req_idnumber;

// With custom questions and privacy consent
$submission = $djep->submissions->create([
    'first_name' => 'Emma',
    'last_name' => 'Wilson',
    'email' => 'emma@example.com',
    'event_date' => '2027-06-20',
    'event_type' => 'Wedding',
    'question_1' => 'Yes, we need lighting',
    'q1_mapto' => 'custom_field1',
    'privacy_policy_signed' => 'true',
    'source' => 'Custom Website',
    'send_notification' => 'true',
]);

Convenience Endpoints

Quick actions without the fields parameter:

// Quick status change — returns old and new status
$result = $djep->events->updateStatus(56789, 'Booked');
echo $result->data->old_status . ' → ' . $result->data->new_status;

// Assign employee to position (1-15), with optional fee and role
$djep->events->assignEmployee(56789, 1, 48113, ['fee' => 500, 'role' => 'Lead DJ']);
$djep->events->assignEmployee(56789, 2, 48361, ['fee' => 350, 'role' => 'MC']);

// Unassign position 3
$djep->events->assignEmployee(56789, 3, 0);

// Update notes — pass any combination of note fields
$djep->events->updateNotes(56789, [
    'comments' => 'AI Summary: Client wants 80s and 90s hits',
    'next_action' => 'Send playlist proposal',
    'next_action_date' => '08/15/2026',
]);

Auto-Pagination

For resources with pagination, use all() to automatically iterate through every page:

// Fetches all events across all pages
foreach ($djep->events->all(['status' => 'Booked']) as $event) {
    echo $event->event_date . "\n";
}

// Works with any paginated resource
foreach ($djep->clients->all() as $client) {
    echo $client->first_name . ' ' . $client->last_name . "\n";
}

Error Handling

The SDK throws specific exceptions for different error types:

use DJEP\Exceptions\AuthenticationException;
use DJEP\Exceptions\NotFoundException;
use DJEP\Exceptions\ValidationException;
use DJEP\Exceptions\ForbiddenException;
use DJEP\Exceptions\RateLimitException;
use DJEP\Exceptions\DJEPException;

try {
    $event = $djep->events->get(99999);
} catch (AuthenticationException $e) {
    // Invalid or missing API key (401)
    echo "Auth error: " . $e->getMessage();
} catch (NotFoundException $e) {
    // Resource not found (404)
    echo "Not found: " . $e->getMessage();
} catch (ForbiddenException $e) {
    // Insufficient permissions (403)
    echo "Forbidden: " . $e->getMessage();
} catch (ValidationException $e) {
    // Invalid parameters (400)
    echo "Validation error: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Too many requests (429)
    echo "Rate limited: " . $e->getMessage();
} catch (DJEPException $e) {
    // Any other API error
    echo "Error: " . $e->getMessage();
}

Configuration Options

$djep = new Client(getenv('DJEP_API_KEY'), getenv('DJEP_DOMAIN'), [
    'timeout' => 60,        // Request timeout in seconds (default: 30)
    'ssl_verify' => false,   // Disable SSL verification (default: true)
]);

Security

Never commit API keys to version control
Store keys in environment variables, .env files (excluded from Git), or config files outside your web root
Use the most restrictive API key for your use case (employee key instead of master admin where possible)
API keys provide full access to the associated account — treat them like passwords

API Documentation

Full API documentation is available at your DJEP instance:

https://yourdomain.com/api/api.asp?action=docs

License

MIT

djeventplannerhub / djep-php-sdk

Maintainers

Package info

Statistics

Security

README

Requirements

Installation

Via Composer (recommended)

Manual Installation

Quick Start

Authentication

Usage

Events

Clients

Venues, Employees, Packages, Addons, Contacts

Vendors

Payments

Music Requests

Booking Helpers

Availability

Settings

Expenses

Other Resources

Create Submission (RFI)

Convenience Endpoints

Auto-Pagination

Error Handling

Configuration Options

Security

API Documentation

License