Do I need a gem to call Finowl from Ruby?

No. net/http, json and uri ship with Ruby, and they are all the examples use. If your app already standardizes on Faraday or HTTP.rb, the request shape is identical: a JSON POST with a bearer token.

Can I use the helper module in a Rails app?

Yes. Put finowl.rb in app/services or lib, make FINOWL_API_KEY available to every process including Puma and Sidekiq, and call it from controllers for interactive checks or from jobs for bulk work.

Is it safe to call the helper from multiple threads?

Yes. The helper creates a new Net::HTTP connection for each call instead of sharing one, so Puma and Sidekiq threads never contend for it. At high volume, add a per-thread or pooled connection to reuse TLS sessions.

How should Ruby code handle the 60 requests per minute limit?

Rescue Finowl::Error, and when status is 429 with code rate_limited, sleep for retry_after and try again. For bulk gender work, use the batch endpoint, since up to 50 items count as one request.

Language · Ruby

Use the Finowl API from Ruby with net/http

Ruby's standard library already has everything a Finowl integration needs. Net::HTTP handles TLS and timeouts, and the json library builds request bodies and parses responses, so there is nothing to add to your Gemfile. That makes the examples here easy to drop into a Rails initializer, a Sinatra route, a Rake task or a Sidekiq worker without negotiating a new dependency with your team. Every endpoint is a POST with a JSON body and a bearer token.

The helper module below wraps one request in a method that reads FINOWL_API_KEY from ENV, sets open and read timeouts, and raises Finowl::Error with the HTTP status, the error code and the Retry-After value whenever the API refuses a call. Rescue that one class and branch on its status. The API pages show standalone scripts you can run with ruby from a terminal, plus advice on background jobs, parameter filtering and rate limits.

Get an API key Read the quickstart

STEP 1

A reusable Ruby client

Keep your key in the FINOWL_API_KEY environment variable and route every call through one helper, so authentication, timeouts and error handling live in one place.

Ruby client

# finowl.rb
require "json"
require "net/http"
require "uri"

module Finowl
  BASE_URI = URI("https://api.finowl.co")

  class Error < StandardError
    attr_reader :status, :code, :retry_after

    def initialize(status, code, retry_after = nil)
      @status = status
      @code = code
      @retry_after = retry_after
      super("Finowl API error #{status}: #{code}")
    end
  end

  def self.post(path, payload)
    http = Net::HTTP.new(BASE_URI.host, BASE_URI.port)
    http.use_ssl = true
    http.open_timeout = 5
    http.read_timeout = 15

    request = Net::HTTP::Post.new(path)
    request["Authorization"] = "Bearer #{ENV.fetch("FINOWL_API_KEY")}"
    request["Content-Type"] = "application/json"
    request.body = JSON.generate(payload)

    response = http.request(request)
    body = JSON.parse(response.body.to_s) rescue {}
    return body if response.is_a?(Net::HTTPSuccess)

    retry_after = response["Retry-After"]&.to_i
    raise Error.new(response.code.to_i, body.dig("error", "code") || "unknown_error", retry_after)
  end
end

# Finowl.post("/v1/breaches/email", { email: "alex@example.com" })

STEP 2

Call the API you need

Check email breaches in Ruby with net/http
A breach lookup in Ruby is one POST to /v1/breaches/email followed by a walk over the breaches array. Each entry is a hash with string keys, so you read breach["Title"], breach["BreachDate"] and breach["DataClasses"] straight from the parsed JSON. The script prints every breach for an address, marks entries whose IsVerified flag is false, and lists the data classes that leaked, which is what you need to decide whether to prompt a password reset.
Check passwords against breach data in Ruby
Checking a password from Ruby takes one request to /v1/breaches/password with the password in the JSON body. Finowl hashes it with SHA-1 and searches by a five-character hash prefix using a k-anonymity range search with padding, and the password is processed transiently: never logged, stored or returned. The response tells you whether it was found and how many times through the breached and count fields.
Predict gender from first names in Ruby
Finowl's /v1/gender/name endpoint takes a name and an optional country code and returns its prediction under a data key. From Ruby you read data["result_status"] first: identified means gender and confidence are filled in, while unknown comes with gender set to nil and a reason such as not_found or ambiguous. The script runs four lookups, including Andrea with two countries, because names can lean differently by region.

A FEW GOOD QUESTIONS

Ruby questions

Other languages and frameworks

Ship with Ruby today

100 free credits every month. Try every request in the sandbox first.

Start building View pricing