post /v2/enrich/companies

Enrich companies

Match companies with our database and enrich it with additional information.

Webhook result: Documentation
Endpoint POST /v2/enrich/companies
Credit cost 0.1 credits / result
Response Asynchronous — results delivered to your webhook
Max per request 10,000 companies

Quickstart#

Map your internal IDs to company identifiers, then send the batch:

curl -X POST "https://api.ocean.io/v2/enrich/companies" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyDataMapping": {
      "crm-001": { "company": { "domain": "stripe.com" } },
      "crm-002": { "company": { "domain": "twilio.com" } },
      "crm-003": {
        "company": { "name": "Acme Corp", "countryCode": "us", "city": "Austin" }
      }
    },
    "webhookUrl": "https://yourapp.com/webhooks/ocean-enrich"
  }'
import requests

response = requests.post(
    'https://api.ocean.io/v2/enrich/companies',
    headers={'X-Api-Token': 'YOUR_API_TOKEN'},
    json={
        'companyDataMapping': {
            'crm-001': {'company': {'domain': 'stripe.com'}},
            'crm-002': {'company': {'domain': 'twilio.com'}},
            'crm-003': {'company': {'name': 'Acme Corp', 'countryCode': 'us', 'city': 'Austin'}},
        },
        'webhookUrl': 'https://yourapp.com/webhooks/ocean-enrich',
    },
)
data = response.json()  # {"status": "in progress"} — results arrive at your webhook
const response = await fetch('https://api.ocean.io/v2/enrich/companies', {
  method: 'POST',
  headers: { 'X-Api-Token': 'YOUR_API_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    companyDataMapping: {
      'crm-001': { company: { domain: 'stripe.com' } },
      'crm-002': { company: { domain: 'twilio.com' } },
      'crm-003': { company: { name: 'Acme Corp', countryCode: 'us', city: 'Austin' } },
    },
    webhookUrl: 'https://yourapp.com/webhooks/ocean-enrich',
  }),
});
const data = await response.json(); // {"status": "in progress"} — results arrive at your webhook

Immediate response:

{ "status": "in progress" }

Webhook payload (when processing completes):

{
  "results": {
    "crm-001": { "status": "found", "company": { "domain": "stripe.com", "name": "Stripe" } },
    "crm-002": { "status": "found", "company": { } },
    "crm-003": { "status": "not_found", "company": null }
  }
}
Result status Meaning
found Matched — enriched data in company field
not_found No match found
triggered Domain not indexed yet — re-enrich in a few minutes

Your webhook must return 2xx to acknowledge delivery. Ocean.io retries on failure with exponential backoff.

Authorizations

apiToken string
x-api-token string

Body application/json

A dictionary where each key is unique user-defined ID for a company, and each value is the data for that company to be enriched. This ID will be included in the webhook response together with the enriched company data, allowing the user to match the response to the original request.
object
webhookUrl string Required
Url of the webhook the enriched companies should be sent to, when completed.
Fields to return in the Company objects. Only requesting the fields that are needed will use less bandwidth and result in faster responses. If not specified, all fields are returned that can be seen in the example.
Array of CompanyField
enum
"domain""countries""primaryCountry""companySize""industryCategories""industries""linkedinIndustry""ecommerce""keywords""employeeCountOcean""employeeCountLinkedin""revenue""yearFounded""description""emails""phones""phones.number""phones.country""phones.primary""logo""technologies""technologyCategories""mobileApps""mobileApps.link""mobileApps.name""webTraffic""webTraffic.visits""webTraffic.pageViews""webTraffic.pagesPerVisit""medias""medias.linkedin""medias.twitter""medias.youtube""medias.facebook""medias.xing""medias.tiktok""medias.instagram""name""legalName""locations""locations.primary""locations.country""locations.locality""locations.region""locations.postalCode""locations.streetAddress""locations.state""locations.regionCode""departmentSizes""rootUrl""faxes""faxes.number""faxes.country""faxes.primary""impressum""impressum.company""impressum.address""impressum.email""impressum.phone""impressum.fax""impressum.vat""impressum.url""impressum.people""fundingRound""fundingRound.date""fundingRound.type""fundingRound.moneyRaisedInUsd""fundingRound.cbUrl""redirectedFrom""updatedAt""headcountGrowth""headcountGrowth.threeMonths""headcountGrowth.threeMonthsPercentage""headcountGrowth.sixMonths""headcountGrowth.sixMonthsPercentage""headcountGrowth.twelveMonths""headcountGrowth.twelveMonthsPercentage""headcountGrowthPerDepartment"

Responses

200 Successful Response
status const Required
Status of the enrichment request. Always `"in progress"` initially, as enrichment is processed asynchronously in the background. Once completed, results for all companies will be sent to the provided webhook.
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

FAQs#

How do I match results back to my records?

The keys in companyDataMapping are echoed back verbatim in the webhook payload. Use them as your record identifiers.

How long does processing take?

Most batches complete within 2–10 minutes. Design your webhook handler to tolerate delay and be idempotent (the same payload may arrive more than once on retries).

What if I have more than 10,000 companies?

Split into batches of up to 10,000 and send as separate requests in parallel (subject to rate limits).