Download the PHP package bestcompany/bestcompany-api without Composer

Bestcompany & Snoball API Wrapper

This package provides Laravel-compatible API wrappers for both Bestcompany and Snoball services, with automatic resource separation and type-safe dependency injection.

Installation

You can install the package via composer:

Then if using laravel publish your config file by running the command.

php artisan vendor:publish --provider="Bestcompany\BestcompanyApi\BestcompanyApiServiceProvider" --tag="config"

Add your api key to the .env using the key from the config file.

Usage

Separate API Clients

This package provides separate API clients for different services:

• BestcompanyApi: Main API for companies, reviews, and general operations
• SnoballApi: Dedicated API for referral-related operations

Using BestcompanyApi

Using SnoballApi

Laravel Usage with Dependency Injection

Available Resources

BestcompanyApi Resources

• bsCompany() - Company management operations
• bsFeatureAdoption() - Feature adoption tracking
• bsReviewActions() - Review action management
• bsUserNotifications() - User notification system
• cache() - Caching operations
• companies() - Company data and operations
• companyPromotionalUrls() - Promotional URL management
• companyReviewLists() - Company review list management
• emails() - Email operations
• factSheetQuestions() - Fact sheet question management
• factSheets() - Fact sheet operations
• fieldReps() - Field representative management
• reviewBsUserFavorites() - User favorite reviews
• reviewMessage() - Review messaging system
• reviews() - Review data and operations
• verticals() - Industry vertical management

SnoballApi Resources

• referralRequest() - Referral request management
• repConversation() - Rep conversation management
• salesRepReferral() - Sales representative referral operations

Configuration

Configuration

The package requires explicit configuration to be passed to each API client. The Laravel service provider handles this automatically using environment variables and config files.

Environment Variables:

Laravel Configuration: After publishing the config files, you can configure these in config/bestcompany-api.php and config/snoball.php:

Manual Configuration: When creating API instances manually (outside of Laravel), you must provide the configuration explicitly:

Note: The API clients no longer fall back to environment variables automatically. Configuration must be explicitly provided either through the Laravel service provider or when creating instances manually.

Laravel Facades (Optional)

You can also use Laravel facades for easier access:

Error Handling

The package automatically prevents cross-API resource access:

The error messages will show you which resources are available for each API client.

Structured request errors (SnoballApi referral requests)

When a Snoball API request fails, the resource throws a typed Bestcompany\BestcompanyApi\Exceptions\SnoballApiException instead of a raw Guzzle exception. It carries a stable, machine-readable Bestcompany\BestcompanyApi\Enums\SnoballApiErrorCode and — importantly — the server's own judgment of whether the error is safe to show an end user, so you never have to string-match a message to decide what to surface:

Switch on $e->errorCode() when you need to react to a specific condition (e.g. SnoballApiErrorCode::ReferralLimitReached). Any code the server introduces before this SDK is upgraded resolves to null; treat unknown codes as not user-safe. Responses that predate the structured envelope degrade gracefully — errorCode() is null, isUserSafe() is false, and getMessage() returns the raw body message.

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Created by Cameron Pope
• Maintained by Braden James
• All Contributors

License

The Apache License 2. Please see License File for more information.

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.