README

A Laravel-ready PHP SDK for the Sumble API, built with Saloon v4.

V1 wraps the endpoints a sales prospecting pipeline needs:

• Account lookup & enrichment — resolve an organization by domain, name, or Sumble id and compose the firmographics and per-technology hiring signals you want back.
• Additional contacts — find people at a resolved account.
• Contact enrichment — reveal a person's email and/or phone.

Other Sumble endpoints (/jobs, /teams, /signals, list management, intelligence briefs, lookups) are intentionally not wrapped yet — add them on demand.

Requirements

• PHP ^8.4
• Laravel ^11.0 || ^12.0 || ^13.0 (for the optional Laravel integration)

Installation

composer require laravel-gtm/sumble-sdk

Configuration (Laravel)

Publish the config:

php artisan vendor:publish --tag=sumble-sdk-config

Environment keys (Sumble authenticates with a Bearer token):

SUMBLE_TOKEN=your-sumble-api-token
SUMBLE_BASE_URL=https://api.sumble.com/v8   # optional; this is the default

Usage

Resolving the SDK

use LaravelGtm\SumbleSdk\SumbleSdk;

// Via the service container (recommended)
$sdk = app(SumbleSdk::class);

// Standalone
$sdk = SumbleSdk::make(token: 'your-sumble-api-token');

Every response DTO exposes creditsUsed and creditsRemaining.

Look up an account

use LaravelGtm\SumbleSdk\Enums\EntityType;
use LaravelGtm\SumbleSdk\Enums\OrganizationAttribute;
use LaravelGtm\SumbleSdk\ValueObjects\EntitySelection;

$response = $sdk->findAccountByDomain('laravel.com',
    attributes: [OrganizationAttribute::Name, OrganizationAttribute::EmployeeCount],
    entities: [new EntitySelection(EntityType::Technology, 'Laravel', ['job_post_count'])],
);

$row = $response->organizations[0] ?? null;
$name = $row?->attributes?->name;
$laravelJobPosts = $row?->entities[0]?->jobPostCount;

Find additional contacts, then reveal contact info

$people = $sdk->findPeople(domain: 'laravel.com', limit: 3);

foreach ($people->people as $person) {
    $contact = $sdk->enrichPerson($person->id, includeEmail: true);
    $emails = $contact->contactInfo?->emails ?? [];
}

Notes

• Rate limit: 60 requests/minute; a 429 backs off for 60s. Errors throw (AlwaysThrowOnErrors); insufficient credits return HTTP 402.
• Credits: email reveal = 10 credits (first per person), phone = 80; repeats are free (cached: true). Paid org attributes cost 1 credit each.
• Recency: Sumble's organization response exposes no per-record last-updated timestamp — a recency-based trust rule against another system cannot rely on one.

Development

composer test        # Pest
composer analyse     # PHPStan (level 8)
composer lint        # Pint (check)
composer format      # Pint (fix)

AI and editor rules

Conventions live under .claude/rules/ (saloon.md, php-package-phpstan.md, laravel-package.md) and are mirrored in .cursor/rules/. Laravel Boost-style helpers live under resources/boost/: the sumble-sdk-development skill and guidelines/core.blade.php document the SDK's methods, value objects, and testing patterns.

License

MIT. See LICENSE.