Copy page

SDKs

PHP SDK

tomba-io/php is the official PHP client for the Tomba API. Each API area is a service class, and each method sends one request.

Requirements

• PHP 8.1 or later, as declared in composer.json.
• The curl and json extensions.

Install

Code
composer require tomba-io/php

Classes are autoloaded from the Tomba namespace; the services are in Tomba\Services.

Authenticate

Create an API key and copy your secret on the API keys page, then export both:

Code
export TOMBA_API_KEY="ta_xxxx"
export TOMBA_SECRET_KEY="ts_xxxx"

The SDK doesn't read environment variables. Pass the values to setKey() and setSecret(), and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. Key expiry and rotation are covered in Authentication.

First request

Find the email address of a person at a company:

Code
<?php

require __DIR__ . '/vendor/autoload.php';

use Tomba\Client;
use Tomba\Services\Finder;

$client = (new Client())
    ->setKey(getenv('TOMBA_API_KEY'))
    ->setSecret(getenv('TOMBA_SECRET_KEY'));

$result = (new Finder($client))->emailFinder('stripe.com', 'Jane', 'Doe');
echo $result['data']['data']['email'], PHP_EOL;

Every method returns an array with two keys: data, the decoded JSON body, and rate_limit. The API wraps its payload in its own data object (Response format), so the address is at $result['data']['data']['email'].

Errors

The SDK throws Tomba\TombaException when the API responds with status 400 or higher, when cURL fails, and before sending a request when a required argument is empty.

Code
<?php

require __DIR__ . '/vendor/autoload.php';

use Tomba\Client;
use Tomba\Services\Finder;
use Tomba\TombaException;

$client = (new Client())
    ->setKey(getenv('TOMBA_API_KEY'))
    ->setSecret(getenv('TOMBA_SECRET_KEY'));

try {
    $result = (new Finder($client))->emailFinder('stripe.com', 'Jane', 'Doe');
    echo $result['data']['data']['email'], PHP_EOL;
} catch (TombaException $e) {
    echo $e->getCode(), ' ', $e->getMessage(), PHP_EOL;
    echo $e->getResponse()['errors']['type'] ?? '', PHP_EOL;
}

Enrichment::person(), company(), and combined() don't throw when nothing is found: those endpoints answer with status 200 and an errors body, so check $result['data']['errors']. Each errors.type is described in Errors.

Rate limits and retries

The SDK doesn't retry. $result['rate_limit'] holds the response's rate limit headers, keyed by header name: x-second-rate-limit, x-minute-rate-limit, x-daily-rate-limit, x-minute-request-left, x-daily-request-left, x-minute-reset-seconds, x-daily-reset-seconds, retry-after, ratelimit-policy, and ratelimit. Numbers are integers, and a header that is absent is null.

A 429 throws TombaException with code 429, without the response headers. Wait before retrying as described in Handle 429 responses.

Requests time out after 120 seconds; the timeout isn't configurable.

Method reference

Create each service with the client, for example new Finder($client).

$type is the {type} segment listed in Bulk types; the order of calls is described in Lifecycle. createBulk() sends a JSON body, so it can't create jobs that need a CSV upload, such as email finder jobs. downloadBulk() returns the results file, a CSV, as a string in $result['data'].

Source

github.com/tomba-io/php (Apache-2.0). Release notes are in CHANGELOG.md.