Copy page

SDKs

Perl SDK

Tomba::Finder is the official Perl client for the Tomba API, published on CPAN in the Tomba-Finder distribution. One Tomba::Finder object exposes every method, and each method sends one request.

Requirements

• Perl 5.26.1 or later, as declared in Makefile.PL.
• LWP::UserAgent, JSON, and URI, installed as dependencies. HTTPS requests also need LWP::Protocol::https.

Install

Code
cpanm Tomba::Finder

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 Tomba::Finder->new($key, $secret), and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. The constructor dies if either value is shorter than 39 characters. Key expiry and rotation are covered in Authentication.

First request

Find the email address of a person at a company:

Code
use strict;
use warnings;

use Tomba::Finder;

my $tomba = Tomba::Finder->new($ENV{TOMBA_API_KEY}, $ENV{TOMBA_SECRET_KEY});

my $result = $tomba->EmailFinder('stripe.com', 'Jane', 'Doe');
die "$result->{data}{errors}{message}\n" if $result->{data}{errors};
print $result->{data}{data}{email} // '', "\n";

Every method returns a hash reference 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

Methods don't die on API errors. They return the decoded error body in data, so check $result->{data}{errors} after every call:

Code
use strict;
use warnings;

use Tomba::Finder;

my $tomba = Tomba::Finder->new($ENV{TOMBA_API_KEY}, $ENV{TOMBA_SECRET_KEY});

my $result = $tomba->EmailFinder('stripe.com', 'Jane', 'Doe');
if (my $error = $result->{data}{errors}) {
    print "$error->{code} $error->{type}: $error->{message}\n";
}
else {
    print $result->{data}{data}{email} // '', "\n";
}

errors.code is the HTTP status. Each errors.type is described in Errors. GET methods die when a response body isn't JSON, for example a gateway timeout page.

Rate limits and retries

The SDK doesn't retry. $result->{rate_limit} holds the response's rate limit headers that are present, 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.

On a 429, $result->{rate_limit}{'retry-after'} holds the wait in seconds. Retry as described in Handle 429 responses.

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

Method reference

Call every method on the Tomba::Finder object. Each method is also available on its own module, for example Tomba::Domain->new($key, $secret)->DomainSearch(...). $opts is an optional hash reference.

$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.

Source

github.com/tomba-io/perl (Apache-2.0). Release notes are in Changes.