post /v2/warmup/companies

Warmup companies

Check available companies in Ocean's database and trigger process of data gathering for the missing ones.

Calling this endpoint does not consume any credits
Endpoint POST /v2/warmup/companies
Credit cost Free
Response Synchronous
Max per request 500 domains

Quickstart#

Use Warmup to pre-check and pre-load domains before you need them for enrichment or lookup:

  1. Call Warmup with your domain list
  2. Domains already indexed → returned in successfulDomains — ready to use
  3. Missing domains → returned in triggeredDomains — background crawling started
  4. Wait 2–5 minutes, then call Warmup again or proceed with enrichment
curl -X POST "https://api.ocean.io/v2/warmup/companies" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["newstartup.io", "anotherdomain.com", "ocean.io"]
  }'
import requests

response = requests.post(
    'https://api.ocean.io/v2/warmup/companies',
    headers={'X-Api-Token': 'YOUR_API_TOKEN'},
    json={'domains': ['newstartup.io', 'anotherdomain.com', 'ocean.io']},
)
data = response.json()
const response = await fetch('https://api.ocean.io/v2/warmup/companies', {
  method: 'POST',
  headers: { 'X-Api-Token': 'YOUR_API_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({ domains: ['newstartup.io', 'anotherdomain.com', 'ocean.io'] }),
});
const data = await response.json();

Example response:

{
  "successfulDomains": ["ocean.io"],
  "triggeredDomains": ["newstartup.io"],
  "ignoredDomains": ["not-a-real-domain"],
  "missingDomains": { "emptypagesite.com": "bad content" },
  "dataErrors": { "partialprofile.io": "missing context vector" }
}
Field Meaning
successfulDomains In the database — ready to use
triggeredDomains Not found — crawling triggered. Retry in 2–5 min.
ignoredDomains Invalid format or not crawlable
missingDomains Crawled but content unsuitable for indexing
dataErrors In database but missing data for some features (e.g., "missing context vector" = can't be used as a lookalike seed)

Authorizations

apiToken string
x-api-token string

Body application/json

Domains to be checked and added to the database if not present
Array of string

Responses

200 Successful Response
Domains that are already present in Ocean's database
Array of string
Domains that are not currently present in Ocean's database. Data gathering process has been triggered for them
Array of string
Invalid domains that failed validation process
Array of string
Domains that are not present in Ocean's database and the reason
object
Domains that are present in Ocean's database but lack the necessary data to perform the search, along with the reason
object
400 Bad Request
detail enum Required
"Conflicting API tokens provided in query parameters and headers"
402 Payment Required
detail enum Required
"Insufficient email credits""Some email verifications are already in progress and might use all your remaining email credits. Please try again later.""Insufficient phone credits""Some phone verifications are already in progress and might use all your remaining phone credits. Please try again later.""Insufficient credits"
403 Forbidden
detail enum Required
"API token should be provided in headers or query parameters""Current API token is not registered in our database"
404 Not found
422 Validation Error
Array of ValidationError
Array of string | integer
string | integer
msg string Required
type string Required
input any
object