Copy page

SDKs

Lua SDK

The tomba rock is the official Lua client for the Tomba API. All methods are on one client object, and each method sends one request.

Requirements

• Lua 5.1, 5.2, or 5.3. The rockspec allows Lua 5.1 or later, but the xml rock that lua-requests depends on requires a version earlier than 5.4.
• LuaRocks and a C++ compiler, to build the dependencies lua-requests and lua-cjson.

Install

Code
luarocks install xml CFLAGS="-O2 -fPIC -std=gnu++14"
luarocks install tomba

The first command builds the xml rock in C++14 mode. Without it, luarocks install tomba fails on compilers that default to C++17, such as GCC 11 and later, because xml doesn't compile as C++17.

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:init(key, secret), and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. init raises an error 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
local Tomba = require("tomba")

local tomba = Tomba:init(os.getenv("TOMBA_API_KEY"), os.getenv("TOMBA_SECRET_KEY"))

local result = tomba:email_finder("stripe.com", "Jane", "Doe")
print(result.data.data.email)

Every method returns a table with two fields: 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. JSON null values decode to cjson.null.

Errors

How a failure surfaces depends on the HTTP method:

• GET methods raise a Lua error when the status isn't 200. The error message is the raw response body, prefixed with the SDK's file and line number.
• POST, PUT, and DELETE methods don't raise on API errors. They return the result table for any status, so check result.data.errors.

Catch GET errors with pcall and decode the body:

Code
local Tomba = require("tomba")
local cjson = require("cjson")

local tomba = Tomba:init(os.getenv("TOMBA_API_KEY"), os.getenv("TOMBA_SECRET_KEY"))

local ok, result = pcall(tomba.email_finder, tomba, "stripe.com", "Jane", "Doe")
if ok then
    print(result.data.data.email)
else
    -- The error message is the response body, prefixed with the SDK's file and line.
    local decoded, body = pcall(cjson.decode, tostring(result):match("{.*") or "")
    if decoded and type(body) == "table" and body.errors then
        print(body.errors.code, body.errors.type, body.errors.message)
    else
        print(result)
    end
end

errors.code is the HTTP status. 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 that are present, keyed by header name, with string values: 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.

A 429 on a GET method raises an error 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

Call every method on the client with a colon, for example tomba:email_finder(...). opts is an optional table.

bulk_type is the {type} segment listed in Bulk types; the order of calls is described in Lifecycle. create_bulk 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/lua, licensed Apache-2.0 in its rockspec.