PHP SDK API Reference

​

Installation & Setup

composer require buena/sdk

<?php
require_once 'vendor/autoload.php';

use Buena\SDK\Configuration;
use Buena\SDK\Api\DefaultApi;
use Buena\SDK\ApiException;

// Initialize configuration
$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.buena.ai/api/v2')
    ->setApiKey('ApiKeyAuth', 'your-api-key');

// Create API instance
$apiInstance = new DefaultApi(new GuzzleHttp\Client(), $config);

​

Core API Methods

​

Lead Management Functions

​

listLeads($limit, $offset, $sort, $order, $search, $company, $status)

• Purpose: List all leads with optional filtering and pagination
• Parameters:
  • $limit (int, optional): Number of leads (default: 50, max: 100)
  • $offset (int, optional): Pagination offset (default: 0)
  • $sort (string, optional): Sort field (created_at, updated_at, first_name, last_name)
  • $order (string, optional): Sort order (asc, desc, default: desc)
  • $search (string, optional): Search term for name/email
  • $company (string, optional): Filter by company name
  • $status (string, optional): Filter by status (active, inactive, contacted)
• Returns: Array of Lead objects with pagination info
• Throws: ApiException on error

​

createLead($createLeadRequest)

• Purpose: Create a new lead in database
• Parameters:
  • $createLeadRequest (CreateLeadRequest): Lead data object
    • first_name (string, required): Lead’s first name
    • last_name (string, required): Lead’s last name
    • email (string, required): Valid email address
    • company (string, optional): Company name
    • phone (string, optional): Phone number
    • linkedin_url (string, optional): LinkedIn profile URL
    • job_title (string, optional): Job title
    • location (string, optional): Location/city
    • notes (string, optional): Additional notes
    • tags (array, optional): Array of tags
    • custom_fields (array, optional): Custom field data
• Returns: Lead object with generated ID and timestamps
• Throws: ApiException on validation error, duplicate email

​

getLead($leadId)

• Purpose: Retrieve specific lead by ID
• Parameters:
  • $leadId (string, required): Unique lead identifier
• Returns: Lead object
• Throws: ApiException if lead not found

​

updateLead($leadId, $updateLeadRequest)

• Purpose: Update existing lead information
• Parameters:
  • $leadId (string, required): Unique lead identifier
  • $updateLeadRequest (UpdateLeadRequest): Update data object
    • All fields optional, same as CreateLeadRequest
    • status (string, optional): Update status (active, inactive, contacted)
• Returns: Updated Lead object
• Throws: ApiException on validation error, lead not found

​

deleteLead($leadId)

• Purpose: Permanently delete lead from database
• Parameters:
  • $leadId (string, required): Unique lead identifier
• Returns: Success confirmation array
• Throws: ApiException if lead not found

​

API Key Management Functions

​

listApiKeys()

• Purpose: List all API keys for account
• Parameters: None
• Returns: Array of ApiKey objects
• Throws: ApiException on insufficient permissions

​

createApiKey($createApiKeyRequest)

• Purpose: Create new API key for account
• Parameters:
  • $createApiKeyRequest (CreateApiKeyRequest): API key data
    • name (string, required): Descriptive name for key
    • permissions (array, required): Array of permission strings
    • expires_at (DateTime, optional): Expiration date
    • description (string, optional): Key description
• Returns: ApiKey object with full key (only returned on creation)
• Throws: ApiException on validation error

​

System Health Functions

​

healthCheck()

• Purpose: Check API system status and connection
• Parameters: None
• Returns: HealthCheck200Response with system status
• Throws: ApiException on server error

​

Data Models

​

Lead Object

class Lead {
    public $id;                    // string: Unique identifier
    public $first_name;            // string: First name
    public $last_name;             // string: Last name
    public $email;                 // string: Email address
    public $company;               // string|null: Company name
    public $phone;                 // string|null: Phone number
    public $linkedin_url;          // string|null: LinkedIn URL
    public $job_title;             // string|null: Job title
    public $location;              // string|null: Location
    public $notes;                 // string|null: Notes
    public $tags;                  // array|null: Tags array
    public $custom_fields;         // array|null: Custom fields
    public $status;                // string: Lead status
    public $created_at;            // DateTime: Creation time
    public $updated_at;            // DateTime: Update time
}

​

ApiKey Object

class ApiKey {
    public $id;                    // string: Unique identifier
    public $name;                  // string: Key name
    public $key;                   // string: Full key (creation only)
    public $key_preview;           // string: Preview (first 8 chars + "...")
    public $permissions;           // array: Permission strings
    public $last_used;             // DateTime|null: Last usage
    public $is_active;             // bool: Active status
    public $created_at;            // DateTime: Creation time
    public $expires_at;            // DateTime|null: Expiration
}

​

Available Permissions

const PERMISSIONS = [
    'leads:read',        // Read leads
    'leads:write',       // Create/update leads
    'leads:delete',      // Delete leads
    'api_keys:read',     // Read API keys
    'api_keys:write',    // Create API keys
    'webhooks:read',     // Read webhooks
    'webhooks:write'     // Create/update webhooks
];

​

Error Handling

• getCode() - HTTP status code
• getMessage() - Error message
• getResponseBody() - Raw response body
• getResponseHeaders() - Response headers

​

Common Error Codes

• 400 - Bad Request (validation errors)
• 401 - Unauthorized (invalid API key)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found (resource doesn’t exist)
• 409 - Conflict (duplicate email)
• 422 - Unprocessable Entity (validation error)
• 429 - Too Many Requests (rate limited)
• 500 - Internal Server Error
• 503 - Service Unavailable

​

Usage Examples

​

Basic Lead Operations

try {
    // List leads
    $leads = $apiInstance->listLeads(25, 0, 'created_at', 'desc');

    // Create lead
    $createRequest = new CreateLeadRequest([
        'first_name' => 'John',
        'last_name' => 'Doe',
        'email' => '[email protected]'
    ]);
    $newLead = $apiInstance->createLead($createRequest);

    // Update lead
    $updateRequest = new UpdateLeadRequest([
        'status' => 'contacted'
    ]);
    $updatedLead = $apiInstance->updateLead($newLead->getId(), $updateRequest);

} catch (ApiException $e) {
    echo "Error: " . $e->getMessage();
}

​

Error Handling Pattern

try {
    $result = $apiInstance->someMethod();
} catch (ApiException $e) {
    switch ($e->getCode()) {
        case 401:
            echo "Invalid API key";
            break;
        case 404:
            echo "Resource not found";
            break;
        case 429:
            echo "Rate limited - retry later";
            break;
        default:
            echo "Error " . $e->getCode() . ": " . $e->getMessage();
    }
}

​

Pagination Helper

function getAllLeads($apiInstance, $pageSize = 50) {
    $allLeads = [];
    $offset = 0;

    do {
        $response = $apiInstance->listLeads($pageSize, $offset);
        $leads = $response->getData();
        $allLeads = array_merge($allLeads, $leads);
        $offset += $pageSize;
    } while (count($leads) === $pageSize);

    return $allLeads;
}