Copy page

SDKs

Dart SDK

The tomba package is the official Dart client for the Tomba API. Each API area is a service class, and each method returns a Future for one request. This page describes version 1.0.3, the current release on pub.dev.

Requirements

• Dart 3, as declared in pubspec.yaml (sdk: '>=3.0.0 <4.0.0').
• The http package, installed as a dependency.

Install

Code
dart pub add tomba

In a Flutter app, run flutter pub add tomba. Everything is exported from package:tomba/tomba.dart.

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. Don't ship your secret in a mobile or web app; call Tomba from your server. Key expiry and rotation are covered in Authentication.

First request

Find the email address of a person at a company:

Code
import 'dart:io';

import 'package:tomba/tomba.dart';

Future<void> main() async {
  final client = Client()
      .setKey(Platform.environment['TOMBA_API_KEY']!)
      .setSecret(Platform.environment['TOMBA_SECRET_KEY']!);

  final result = await Finder(client).emailFinder(
    domain: 'stripe.com',
    firstName: 'Jane',
    lastName: 'Doe',
  );
  print(result.data['data']['email']);
}

Every method returns a Response with two fields: data, the decoded JSON body, and rateLimit. 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 TombaException when the API responds with status 400 or higher and when the request fails.

Code
import 'dart:io';

import 'package:tomba/tomba.dart';

Future<void> main() async {
  final client = Client()
      .setKey(Platform.environment['TOMBA_API_KEY']!)
      .setSecret(Platform.environment['TOMBA_SECRET_KEY']!);

  try {
    final result = await Finder(client).emailFinder(
      domain: 'stripe.com',
      firstName: 'Jane',
      lastName: 'Doe',
    );
    print(result.data['data']['email']);
  } on TombaException catch (e) {
    print('${e.code} ${e.message}');
    print(e.response?['errors']?['type']);
  }
}

Each errors.type is described in Errors.

Rate limits and retries

The SDK doesn't retry. result.rateLimit holds the response's rate limit headers as String? fields: xSecondRateLimit, xMinuteRateLimit, xDailyRateLimit, xMinuteRequestLeft, xDailyRequestLeft, xMinuteResetSeconds, xDailyResetSeconds, retryAfter, rateLimitPolicy, and rateLimit.

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 Finder(client). All arguments are named.

Source

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