Copy page

SDKs

Go SDK

github.com/tomba-io/go is the official Go client for the Tomba API. All methods hang off one client value, and each method sends one request.

Requirements

Go 1.18 or later, as declared in go.mod. The module has no third-party dependencies.

Install

Code
go get github.com/tomba-io/go

Import the github.com/tomba-io/go/tomba package.

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.New(key, secret), 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
package main

import (
	"fmt"
	"log"
	"os"

	"github.com/tomba-io/go/tomba"
)

func main() {
	client := tomba.New(os.Getenv("TOMBA_API_KEY"), os.Getenv("TOMBA_SECRET_KEY"))

	result, err := client.EmailFinder(tomba.Params{
		"domain":     "stripe.com",
		"first_name": "Jane",
		"last_name":  "Doe",
	})
	if err != nil {
		log.Fatal(err)
	}

	if data, ok := result.Data.(map[string]interface{}); ok {
		fmt.Println(data["email"])
	}
}

Most methods decode the response body into a type from the github.com/tomba-io/go/tomba/models package; the keys, leads, lists, attributes, and flag methods return the raw body as json.RawMessage. models.Finder.Data is an interface{}, so assert it to a map before reading fields.

tomba.Params is a map[string]interface{}. On GET requests only string, int, and bool values are sent, and empty strings and zero integers are skipped.

Errors

Every method returns an error when the request fails or the API responds with a status other than 200 or 201. The error text holds only the HTTP status, for example error: 400 Bad Request, status code: 400. The SDK discards the response body, so the API's errors.type and errors.message aren't available; the causes behind each status are listed in Errors.

Code
package main

import (
	"fmt"
	"log"
	"os"

	"github.com/tomba-io/go/tomba"
)

func main() {
	client := tomba.New(os.Getenv("TOMBA_API_KEY"), os.Getenv("TOMBA_SECRET_KEY"))

	result, err := client.EmailFinder(tomba.Params{
		"domain":     "stripe.com",
		"first_name": "Jane",
		"last_name":  "Doe",
	})
	if err != nil {
		if wait := client.LastRateLimit.RetryAfter; wait > 0 {
			log.Fatalf("rate limited, retry in %d seconds", wait)
		}
		log.Fatal(err) // for example "error: 400 Bad Request, status code: 400"
	}

	fmt.Println(result.Data)
}

PersonFind, CompanyFind, and CombinedFind don't return an error when nothing is found: those endpoints answer with status 200 and an errors body, which doesn't fit the result model, so the model comes back empty.

Rate limits and retries

The SDK doesn't retry. After every response, including failed ones, the client stores the rate limit headers in client.LastRateLimit, a tomba.RateLimit with the fields SecondLimit, MinuteLimit, DailyLimit, MinuteRemaining, DailyRemaining, MinuteReset, DailyReset, RetryAfter, Policy, and RateLimit. A header that is absent reads as 0. Each call overwrites the field, so read it right after the call, and don't rely on it when one client sends requests from several goroutines. tomba.ParseRateLimit(*http.Response) parses the same headers from any response.

RetryAfter is set only on a 429. Wait at least that long, as described in Handle 429 responses.

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

Method reference

All methods are on *tomba.Tomba, the value returned by tomba.New. Result types are in the models package.

models.BulkType has one constant per bulk type, from models.BulkTypeSearch to models.BulkTypePhoneValidator; the order of calls is described in Lifecycle. GetAllSearchBulks, GetAllFinderBulks, and the other GetAll…Bulks(params) methods call GetAllBulks for one type. SaveBulkResults downloads the results and writes them to filePath.

Source

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