PHPackages mcore-services/teamleader-sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. mcore-services/teamleader-sdk ActiveLibrary[API Development](/categories/api) mcore-services/teamleader-sdk ============================= Laravel SDK for Teamleader Focus API v1.2.7(1mo ago)0311MITPHPPHP ^8.2CI passing Since Oct 17Pushed 1mo agoCompare [ Source](https://github.com/MCore-Services-bv/teamleader-sdk)[ Packagist](https://packagist.org/packages/mcore-services/teamleader-sdk)[ Fund](https://www.buymeacoffee.com/mcoreservices)[ GitHub Sponsors](https://github.com/mcore-services-bv)[ RSS](/packages/mcore-services-teamleader-sdk/feed)WikiDiscussions main Synced today READMEChangelog (10)Dependencies (18)Versions (16)Used By (0) Teamleader Focus SDK for Laravel ================================ [](#teamleader-focus-sdk-for-laravel) [![Latest Version](https://camo.githubusercontent.com/94ba1fdabb275a1453f104cd179d231b3578b226444d263bb52c069d0d3dfa9f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f4d436f72652d53657276696365732d62762f7465616d6c65616465722d73646b)](https://github.com/MCore-Services-bv/teamleader-sdk/releases)[![Total Downloads](https://camo.githubusercontent.com/ccd615e20c0e60a84fb4f25bff6454fc1ebdf2da9081a23d641342b6c55afd77/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d636f72652d73657276696365732f7465616d6c65616465722d73646b)](https://packagist.org/packages/mcore-services/teamleader-sdk)[![PHP Version](https://camo.githubusercontent.com/6a7e530361296f219d5472a42f4d5f6661ef84e9e117be1dea29c9adf8f963a6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d636f72652d73657276696365732f7465616d6c65616465722d73646b)](https://packagist.org/packages/mcore-services/teamleader-sdk)[![Laravel Version](https://camo.githubusercontent.com/ef7c96582f5f2563be42da06ff61bb526d4e2e009e26462fae69095915cd917d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d3130253230253743253230313125323025374325323031322d626c7565)](https://laravel.com)[![License](https://camo.githubusercontent.com/ed885c5b317d6977d6f0a7cbe61b4f3104bcbff03894273d2af8dbac9e5ab5e8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4d436f72652d53657276696365732d62762f7465616d6c65616465722d73646b)](https://github.com/MCore-Services-bv/teamleader-sdk/blob/main/LICENSE.md) A comprehensive, production-ready Laravel package for integrating with the Teamleader Focus API. Built with modern Laravel best practices, featuring automatic token management, intelligent rate limiting, resource sideloading, and complete coverage of all Teamleader Focus API endpoints. **Quick Links:** - πŸ“¦ **Packagist:** [packagist.org/packages/mcore-services/teamleader-sdk](https://packagist.org/packages/mcore-services/teamleader-sdk) - πŸ’» **GitHub:** [github.com/MCore-Services-bv/teamleader-sdk](https://github.com/MCore-Services-bv/teamleader-sdk) - πŸ“– **Full Docs:** [/docs folder](https://github.com/MCore-Services-bv/teamleader-sdk/tree/main/docs) --- ✨ Key Features -------------- [](#-key-features) ### πŸ” Authentication & Security [](#-authentication--security) - **Complete OAuth 2.0 Flow** β€” Authorization URL generation and secure callback handling - **Automatic Token Management** β€” Smart token refresh with database and cache layers - **Concurrent Request Safety** β€” Distributed locking prevents token refresh race conditions ### πŸš€ Performance & Reliability [](#-performance--reliability) - **Intelligent Rate Limiting** β€” Built-in sliding window rate limiter with automatic throttling (200 req/min) - **Response Caching** β€” Configurable caching for static data endpoints - **Connection Pooling** β€” Optimized HTTP client with configurable timeouts - **Retry Logic** β€” Automatic retry with exponential backoff for transient failures ### πŸ“¦ Developer Experience [](#-developer-experience) - **Resource-Based Architecture** β€” Intuitive, organized access to all API endpoints - **Fluent Sideloading Interface** β€” Reduce API calls by including related resources - **Comprehensive Validation** β€” Request validation before API calls - **Rich Error Handling** β€” Detailed, actionable error messages - **Extensive Logging** β€” Debug-friendly logging with configurable levels - **Resource Introspection** β€” Query capabilities of any resource programmatically ### 🎯 Complete API Coverage [](#-complete-api-coverage) **CRM Resources** - Companies (incl. logo upload, marketing consent, price list sideload), Contacts (incl. avatar upload), Business Types, Tags, Addresses **Deals & Sales** - Deals, Quotations (incl. rich text content), Orders (incl. order number, project/group/purchase price on line items), Pipelines, Phases, Sources, Lost Reasons **Invoicing** - Invoices (incl. delivery date, PEPPOL status), Credit Notes (incl. PEPPOL status), Payment Methods, Payment Terms, Tax Rates, Withholding Tax Rates, Commercial Discounts, Subscriptions (incl. PEPPOL sending method) **Expenses** - Expenses (incl. payment filters & status), Incoming Invoices (full payment management), Incoming Credit Notes (full payment management), Receipts (full payment management), Bookkeeping Submissions **Projects & Time Tracking** - Projects (v1 & v2), Project Tasks, Milestones, Materials (incl. estimated quantity), Time Tracking (incl. nextgenProject filter), Timers **Planning** *(new in v1.2.0)* - Reservations, User Availability, Plannable Items **Calendar & Activities** - Meetings (incl. group field), Calls, Call Outcomes, Calendar Events, Activity Types **Products & Services** - Products, Product Categories, Unit of Measures, Work Types **General Management** - Users, Departments, Custom Fields (incl. create), Currencies, Notes, Files (incl. temporary subject type) **System & Migration** - Webhooks (incl. PEPPOL events), Cloud Platforms, Accounts, Migration Utilities --- πŸ“‹ Requirements -------------- [](#-requirements) - **PHP**: 8.2 or higher - **Laravel**: 10.x, 11.x, or 12.x - **Extensions**: ext-json, ext-mbstring - **Database**: MySQL 5.7+, PostgreSQL 10+, or SQLite 3.8+ --- πŸš€ Installation -------------- [](#-installation) ### 1. Install via Composer [](#1-install-via-composer) ``` composer require mcore-services/teamleader-sdk ``` ### 2. Publish the Configuration [](#2-publish-the-configuration) ``` php artisan vendor:publish --provider="McoreServices\TeamleaderSDK\TeamleaderServiceProvider" ``` ### 3. Configure Environment Variables [](#3-configure-environment-variables) Add to your `.env` file: ``` TEAMLEADER_CLIENT_ID=your_client_id TEAMLEADER_CLIENT_SECRET=your_client_secret TEAMLEADER_REDIRECT_URI=https://your-app.com/teamleader/callback ``` ### 4. Set Up OAuth Routes [](#4-set-up-oauth-routes) ``` // routes/web.php use McoreServices\TeamleaderSDK\Facades\Teamleader; Route::get('/teamleader/auth', function () { return redirect(Teamleader::getAuthorizationUrl()); }); Route::get('/teamleader/callback', function (Request $request) { Teamleader::handleCallback($request->code, $request->state); return redirect('/dashboard')->with('success', 'Connected to Teamleader!'); }); ``` > **Note:** No `php artisan migrate` is required. The SDK automatically creates the `teamleader_tokens` table on first use. --- πŸ”‘ Authentication ---------------- [](#-authentication) ``` use McoreServices\TeamleaderSDK\Facades\Teamleader; // 1. Redirect user to Teamleader for authorization $authUrl = Teamleader::getAuthorizationUrl(); return redirect($authUrl); // 2. Handle the callback (tokens are stored automatically) Teamleader::handleCallback($code, $state); // 3. Check authentication status if (Teamleader::isAuthenticated()) { // Ready to make API calls } ``` --- πŸ“– Basic Usage ------------- [](#-basic-usage) ### Companies [](#companies) ``` use McoreServices\TeamleaderSDK\Facades\Teamleader; // List companies with filters and sideloading $companies = Teamleader::companies()->list( filters: ['status' => 'active'], includes: ['primary_address', 'price_list'] ); // Get a single company $company = Teamleader::companies()->info('company-uuid'); // Create a company $company = Teamleader::companies()->create([ 'name' => 'Acme Corp', 'email' => [['type' => 'primary', 'email' => 'info@acme.com']], 'marketing_mails_consent' => true, ]); // Upload a company logo Teamleader::companies()->uploadLogo('company-uuid', 'file-uuid'); ``` ### Contacts [](#contacts) ``` // List contacts with price list sideload $contacts = Teamleader::contacts()->list( filters: ['marketing_mails_consent' => true], includes: ['primary_address', 'price_list'] ); // Upload a contact avatar Teamleader::contacts()->uploadAvatar('contact-uuid', 'file-uuid'); ``` ### Invoices [](#invoices) ``` // Create a draft invoice with delivery date $invoice = Teamleader::invoices()->draft([ 'invoicee' => ['type' => 'company', 'id' => 'company-uuid'], 'delivery_date' => '2026-03-15', 'grouped_lines' => [...] ]); // List invoices (includes peppol_status, delivery_date) $invoices = Teamleader::invoices()->list( filters: ['status' => 'outstanding'] ); ``` ### Expenses & Payment Management [](#expenses--payment-management) ``` // List expenses with payment filters $expenses = Teamleader::expenses()->list(filters: [ 'payment_statuses' => ['not_paid', 'partially_paid'], 'department_ids' => ['dept-uuid'], 'paid_at' => ['from' => '2026-01-01', 'to' => '2026-03-31'], ]); // Manage payments on an incoming invoice Teamleader::incomingInvoices()->registerPayment( id: 'invoice-uuid', payment: ['amount' => ['amount' => 250.00, 'currency' => 'EUR']], paidAt: '2026-03-11', paymentMethodId: 'method-uuid', remark: 'Partial payment' ); $payments = Teamleader::incomingInvoices()->listPayments('invoice-uuid'); // Same API available for incoming credit notes and receipts Teamleader::incomingCreditnotes()->registerPayment(...); Teamleader::receipts()->registerPayment(...); ``` ### Planning (New in v1.2.0) [](#planning-new-in-v120) ``` // List reservations $reservations = Teamleader::reservations()->list( filters: ['user_id' => 'user-uuid'], options: ['page' => ['size' => 20]] ); // Create a reservation Teamleader::reservations()->create([ 'user_id' => 'user-uuid', 'starts_on' => '2026-03-20', 'ends_on' => '2026-03-21', ]); // Check user availability $availability = Teamleader::userAvailability()->daily([ 'user_id' => 'user-uuid', 'from' => '2026-03-01', 'to' => '2026-03-31', ]); // List plannable items $items = Teamleader::plannableItems()->list(['type' => 'task']); ``` ### Custom Field Definitions (New endpoint) [](#custom-field-definitions-new-endpoint) ``` // Create a custom field definition $field = Teamleader::customFieldDefinitions()->create([ 'context' => 'company', 'type' => 'text', 'label' => 'VAT Number', 'required' => false, 'trackable' => false, ]); ``` --- ⚑ Rate Limiting & Caching ----------------------------- [](#-rate-limiting--caching) ``` // Check rate limit status $stats = Teamleader::getRateLimitStats(); echo "Remaining: {$stats['remaining']} / {$stats['limit']}"; // Configure caching per resource $companies = Teamleader::companies() ->withCache(ttl: 3600) ->list(); ``` --- πŸ”— Resource Sideloading ---------------------- [](#-resource-sideloading) ``` // Include related resources to reduce API calls $deals = Teamleader::deals()->list( filters: ['status' => 'open'], includes: ['lead.customer', 'responsible_user', 'phase'] ); // Validate available includes for a resource $available = Teamleader::companies()->getAvailableIncludes(); ``` --- πŸͺ Webhooks ---------- [](#-webhooks) ``` // Register a webhook Teamleader::webhooks()->create([ 'url' => 'https://your-app.com/webhooks/teamleader', 'types' => [ 'invoice.created', 'invoice.peppolSubmissionSucceeded', 'invoice.peppolSubmissionFailed', 'creditNote.peppolSubmissionSucceeded', 'creditNote.peppolSubmissionFailed', ], ]); ``` --- πŸ› οΈ Error Handling ----------------- [](#️-error-handling) ``` use McoreServices\TeamleaderSDK\Exceptions\TeamleaderApiException; use McoreServices\TeamleaderSDK\Exceptions\TeamleaderAuthException; try { $company = Teamleader::companies()->info('invalid-uuid'); } catch (TeamleaderApiException $e) { logger()->error('Teamleader API error', [ 'message' => $e->getMessage(), 'status' => $e->getStatusCode(), 'errors' => $e->getErrors(), ]); } catch (TeamleaderAuthException $e) { // Token expired and refresh failed β€” re-authenticate return redirect('/teamleader/auth'); } ``` --- 🀝 Contributing -------------- [](#-contributing) Contributions are welcome! 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Write tests for your changes 4. Ensure all tests pass (`composer test`) 5. Commit your changes (`git commit -m 'Add amazing feature'`) 6. Push to the branch (`git push origin feature/amazing-feature`) 7. Open a Pull Request Please follow PSR-12 coding standards and write tests for new features. --- πŸ”’ Security ---------- [](#-security) If you discover any security-related issues, please email **** instead of using the issue tracker. --- πŸ“ Changelog ----------- [](#-changelog) Please see [CHANGELOG.md](CHANGELOG.md) for information on what has changed recently. --- πŸ“œ License --------- [](#-license) The MIT License (MIT). Please see [LICENSE.md](LICENSE.md) for more information. --- πŸ™ Credits --------- [](#-credits) - **MCore Services** β€” - Built with ❀️ for the Laravel and Teamleader communities πŸ’¬ Support --------- [](#-support) - **Documentation**: [/docs folder](https://github.com/MCore-Services-bv/teamleader-sdk/tree/main/docs) - **Email**: - **Issues**: [GitHub Issues](https://github.com/mcore-services-bv/teamleader-sdk/issues) - **Discussions**: [GitHub Discussions](https://github.com/mcore-services-bv/teamleader-sdk/discussions) - **Teamleader API**: [developer.focus.teamleader.eu](https://developer.focus.teamleader.eu/) πŸ—ΊοΈ Roadmap ---------- [](#️-roadmap) - Bulk operations helper - Enhanced caching strategies with tag-based invalidation - Laravel Pulse integration - CLI tool for quick API exploration --- **Made with ❀️ by [MCore Services](https://mcore-services.be)** ### Health Score 44 β€” FairBetter than 90% of packages Maintenance90 Actively maintained with recent releases Popularity14 Limited adoption so far Community6 Small or concentrated contributor base Maturity56 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~14 days Total 15 Last Release 52d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/1c9048dc87aab9f21cc84594acdbf9049c15f1cd747b523800e152e19a40393f?d=identicon)[MC0RE](/maintainers/MC0RE) --- Top Contributors [![MC0R3](https://avatars.githubusercontent.com/u/84664431?v=4)](https://github.com/MC0R3 "MC0R3 (102 commits)") --- Tags laravelteamleadertlf ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/mcore-services-teamleader-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/mcore-services-teamleader-sdk/health.svg)](https://phpackages.com/packages/mcore-services-teamleader-sdk) ``` ### Alternatives [craftcms/cms Craft CMS 3.6k3.6M3.1k](/packages/craftcms-cms)[tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3741.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5021.9k](/packages/simplestats-io-laravel-client)[eslazarev/wildberries-sdk Wildberries OpenAPI clients (generated). 273.0k](/packages/eslazarev-wildberries-sdk)[jasara/php-amzn-selling-partner-api A fluent interface for Amazon's Selling Partner API in PHP 1348.7k1](/packages/jasara-php-amzn-selling-partner-api) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)