FinowlLanguage · Go
Integrate the Finowl API in Go with net/http
Go's standard library already has everything needed for Finowl: net/http for the request, encoding/json for the body, and context for cancellation. There is nothing to vendor and no generated client to keep in sync. Decoding into structs gives you compile-time field names for breach records and gender predictions, which suits API gateways, signup services and batch workers written in Go that need predictable behavior under load.
The package below exposes a single Post function that takes a context, a path, an input value and a pointer to decode into, backed by one shared http.Client with a timeout. Non-200 responses become a typed *finowl.Error carrying Status, Code and a RetryAfter duration, so callers can use errors.As to decide whether to wait, give up or alert. Each API page shows a standalone main package you can run with go run main.go.
STEP 1
A reusable Go 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.
package finowl
import (
"bytes"
"context"
"encoding/json"
"fmt"
"net/http"
"os"
"strconv"
"time"
)
var (
baseURL = "https://api.finowl.co"
client = &http.Client{Timeout: 10 * time.Second}
)
type Error struct {
Status int
Code string
RetryAfter time.Duration
}
func (e *Error) Error() string { return fmt.Sprintf("finowl: %d %s", e.Status, e.Code) }
func Post(ctx context.Context, path string, in, out any) error {
body, err := json.Marshal(in)
if err != nil {
return err
}
req, err := http.NewRequestWithContext(ctx, http.MethodPost, baseURL+path, bytes.NewReader(body))
if err != nil {
return err
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("FINOWL_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
if resp.StatusCode == http.StatusOK {
return json.NewDecoder(resp.Body).Decode(out)
}
var e struct{ Error struct{ Code string } }
_ = json.NewDecoder(resp.Body).Decode(&e)
secs, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
return &Error{Status: resp.StatusCode, Code: e.Error.Code, RetryAfter: time.Duration(secs) * time.Second}
}STEP 2
Call the API you need
Check email breaches in Go with net/http
Go decodes the email breach response into structs with very little ceremony. The breach records use PascalCase keys, so fields named Title, BreachDate, DataClasses and IsVerified line up with the JSON without any struct tags. The envelope fields breached and breaches also match exported Go fields because encoding/json compares names case-insensitively when no tag is present.
Check breached passwords in Go before storing them
In a Go auth service the password check belongs right before you call bcrypt or argon2 on the new password. The Finowl endpoint takes the plaintext over HTTPS, hashes it with SHA-1, searches by a 5-character prefix with padding, and returns breached and count. The password is processed transiently and is never logged, stored or returned, so the only place it can leak is your own code.
Predict gender from names in Go with net/http
The gender name endpoint wraps its prediction in a data object, so the Go example decodes into a small envelope struct with a Prediction inside. Fields like result_status and confidence_kind use snake_case, which is where json struct tags earn their keep. Gender is a pointer so a JSON null becomes nil, which matches how the API represents unknown results, while Reason is a plain string that stays empty for identified names.
A FEW GOOD QUESTIONS
Go questions
Other languages and frameworks
Ship with Go today
100 free credits every month. Try every request in the sandbox first.