README

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

The SDK wraps every documented v9 endpoint:

Organizations — resolve companies by domain/name/id or search by technology, job function, industry, and firmographics; compose exactly which attributes and per-entity metrics return; retrieve recent organization signals and AI intelligence briefs.
People (async) — resolve people by id/LinkedIn/email or search within organizations; compose attributes including contact reveals (email, phone) and inferred managers/direct reports.
Job posts — resolve jobs by id or search by organization and filters; full descriptions, extracted technologies/teams/functions/projects, and scored hiring managers.
Teams — resolve or search teams with breadcrumbs, ICP fit scores, related people, and their job posts.
Lookups — technologies, technology categories, projects, and job-title → function/level classification.
Signals — filtered signal feeds and AI Priority Signals digests.
Lists — organization and contact list management.
Support — data-quality reports and support requests.

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/v9   # 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');

Endpoints are grouped into resources — organizations(), people(), jobs(), teams(), technologies(), projects(), signals(), organizationLists(), contactLists(), and support(). 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 ?? null;

Search organizations by tech stack

$response = $sdk->organizations()->search(
    "technology EQ 'kubernetes' AND employee_count GT 1000",
    attributes: [OrganizationAttribute::Name, OrganizationAttribute::Industry],
    limit: 50,
);

Enrich people (asynchronous)

use LaravelGtm\SumbleSdk\Enums\PersonAttribute;
use LaravelGtm\SumbleSdk\ValueObjects\PersonInput;

$pending = $sdk->people()->enrich(
    [PersonInput::linkedinUrl('https://www.linkedin.com/in/someone')],
    attributes: [PersonAttribute::Name, PersonAttribute::JobTitle, PersonAttribute::Email],
);

$result = $sdk->people()->wait($pending->requestId);

foreach ($result->people ?? [] as $person) {
    $email = $person->attributes?->email;
}

POST /people starts a background job in both modes; wait() polls until it finishes (credits are charged once, on the first successful poll). Contact attributes must be requested explicitly — they are never part of 'all'.

Signals and intelligence

use LaravelGtm\SumbleSdk\Enums\SignalPriority;
use LaravelGtm\SumbleSdk\ValueObjects\SignalsFilter;

$signals = $sdk->signals()->search(new SignalsFilter(
    organizationIds: [31],
    priorities: [SignalPriority::High],
));

$brief = $sdk->organizations()->intelligenceBrief(31);
if ($brief->pending) {
    // retry after $brief->retryAfterSeconds
}

Notes

Rate limit: 10 requests/second across all endpoints; a 429 backs off for 60s. Errors throw (AlwaysThrowOnErrors); insufficient credits return HTTP 402 before any work is done.
Credits: you only pay for what you select. Email reveal = 10 credits (first per person), phone = 80, input-email resolution = 20, intelligence brief = 50, signals = 1 per signal returned. Unmatched inputs are free.
Slugs first: advanced query filters expect canonical slugs — resolve them via $sdk->technologies(), $sdk->projects(), or $sdk->jobs()->lookupTitles().
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/:

skills/sumble-sdk-development — every resource/method with examples, the composable select pattern, async people workflow, credit rules, and testing patterns.
skills/sumble-docs-research — how to research the Sumble REST API through Sumble's documentation MCP server (https://docs.sumble.com/~gitbook/mcp) to pick the right endpoint and fields before writing code.
guidelines/core.blade.php — condensed guidelines for agents working in consuming apps.

License

MIT. See LICENSE.

laravel-gtm / sumble-sdk

Maintainers

Package info

Statistics

Security