How to Look Up Companies by Domain (in Ruby)

You send a domain to POST /v1/companies/enrich and get one company record back. This page gives you a Ruby script that does that for a list of domains, with retries and paging.

TL;DR

• It takes about 10 minutes and uses only Ruby's standard library (net/http and json).
• It spends one LeadOcean record per company returned. A 404 (domain not in our data) is free, so the Free plan's 1,000 records cover 1,000 hits.
• It retries on 429 using the Retry-After header and writes one JSON line per company.

Prerequisites

• Ruby 3.0 or newer.
• A LeadOcean API key, exported as $LEADOCEAN_API_KEY. The Free plan gives one key, no card.
• A file domains.txt with one domain per line, for example acme.com.

Step 1: Send one request

The endpoint takes a flat JSON body with domain or linkedin_url. Auth is the x-api-key header. Test it with curl before writing Ruby.

curl -s https://api.leadocean.io/v1/companies/enrich \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme.com"}'

A hit returns 200 with a data object. A miss returns 404.

Step 2: Write the Ruby script

Save this as lookup.rb. It reads domains.txt, calls the API once per domain and prints JSON Lines to stdout.

require "net/http"
require "json"

KEY = ENV.fetch("LEADOCEAN_API_KEY")
BASE = URI("https://api.leadocean.io")

def post(http, path, body)
  5.times do
    req = Net::HTTP::Post.new(path, "x-api-key" => KEY, "Content-Type" => "application/json")
    req.body = body.to_json
    res = http.request(req)
    case res.code.to_i
    when 200 then return JSON.parse(res.body)
    when 404 then return nil
    when 429 then sleep([res["Retry-After"].to_i, 1].max)
    else abort("#{body}: HTTP #{res.code} #{res.body}")
    end
  end
  abort("#{body}: still rate limited")
end

Net::HTTP.start(BASE.host, BASE.port, use_ssl: true, read_timeout: 30) do |http|
  File.readlines("domains.txt", chomp: true).map(&:strip).reject(&:empty?).each do |domain|
    company = post(http, "/v1/companies/enrich", { domain: domain })
    puts JSON.generate(company) if company
  end
end

The 429 branch waits for the number of seconds in Retry-After, then tries again, up to five times. A 429 costs no records.

Step 3: Run it and save the results

printf 'acme.com\nexample.org\n' > domains.txt
ruby lookup.rb > companies.jsonl
wc -l companies.jsonl

Each line is one company. Misses are skipped, so the line count can be lower than the domain count. The loop is sequential on purpose. One call at a time rarely passes the Free plan's 5 requests a second, and the 429 branch covers the rest.

Step 4: Page through a search when you do not have the domains yet

Enrich returns one company per call, so there is nothing to page. If you need to build the domain list first, call POST /v1/companies/search. The body is flat JSON, filters are arrays, limit runs 1 to 100, and you pass the cursor from the previous page to get the next one.

cursor = nil
loop do
  body = { country: ["US"], limit: 100 }
  body[:cursor] = cursor if cursor
  page = post(http, "/v1/companies/search", body)
  page["data"].each { |c| puts JSON.generate(c) }
  cursor = page.dig("meta", "nextCursor")
  break unless cursor
end

Run this inside the same Net::HTTP.start block, in place of the domain loop. One search pages to 10,000 rows. The last page has meta.depthCapped true and no nextCursor. Narrow the filters instead of walking further. To size the list first, call GET /v1/companies/count, which is free. Search spends one record per company returned, so check the count before you page.

What you get

This is the response shape from the API reference, with placeholder values. A hit is wrapped as success, data and meta, and data holds these groups.

{
  "success": true,
  "data": {
    "company_data": {
      "company_name": "Acme",
      "company_domain": "acme.com",
      "company_type": "Privately Held",
      "company_industries": [{ "name2": "Software Development", "priority": 1 }],
      "company_employees": { "number_of_employees": 120, "number_of_employees_code": "51-200" },
      "company_primary_address": { "city": "San Francisco", "country_code": "US" },
      "company_number_of_detected_technologies": 2
    },
    "company_detected_technologies": [
      { "technology_product": { "name": "Example CDN" }, "technology_category": { "name2": "Content Delivery Network" } }
    ],
    "company_metrics": { "completion_score": 90, "marketability_score": 80 },
    "meta": { "sources": ["own"], "schema": "leadocean.company.v1" }
  },
  "meta": { "source": "leadocean" }
}

Response shape from the company lookup docs (October 2026), placeholder values. Fields we hold nothing for come back as null. company_data also carries funding, revenue, NAICS and SIC codes, and company_number_of_profiles when we hold them.

Troubleshooting

FAQ