POST /enrich_companies_bulk • Credits: 1 credit per company returned

Bulk Company Enrichment returns LinkedIn company profiles for up to 50 numeric company IDs in one synchronous call. The response is a JSON array with one object for each company that RichAPI finds. Each company returned costs 1 credit, and a company that RichAPI does not find costs nothing.

What does Bulk Company Enrichment do?

Sales and marketing teams hold long lists of LinkedIn company IDs without firmographic data. One call per company is slow at list scale. Bulk Company Enrichment reads up to 50 LinkedIn company profiles in a single request. The data source is LinkedIn. The endpoint returns the companies in one array in the same response. For a single company, send Company Enrichment API instead.

Which endpoint does Bulk Company Enrichment use?

Method: POST
URL: https://api.richapi.ai/api/v1/enrich_companies_bulk
Authentication: x-api-key header
Response: synchronous JSON array
Maximum batch size: 50 company IDs
Credits: 1 credit per company returned

How to send a Bulk Company Enrichment request

Copy your API key from the RichAPI dashboard.
Collect the numeric LinkedIn company IDs of the companies that you want.
Split the list into batches of 50 company IDs or fewer.
Set the urns parameter to one batch.
Send a POST request to https://api.richapi.ai/api/v1/enrich_companies_bulk.
Send the API key in the x-api-key header.
Read the company objects from the response array.

CAUTION: Do not send more than 50 company IDs in one Bulk Company Enrichment request. The maximum batch size is 50 company IDs. Split a longer list into batches of 50.

cURL

curl -X POST https://api.richapi.ai/api/v1/enrich_companies_bulk   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "urns": [
      "1586",
      "1035"
    ]
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/enrich_companies_bulk",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "urns": [
            "1586",
            "1035",
        ]
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/enrich_companies_bulk", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urns: ["1586", "1035"],
  }),
});

const data = await response.json();
console.log(data);

What parameters does Bulk Company Enrichment accept?

Parameter	Type	Required	Default	Description
`urns`	array of strings	Yes	`[]`	The numeric LinkedIn company IDs, for example `1586`. Maximum 50 per request.

urns is the only parameter that Bulk Company Enrichment accepts. Any other field in the request body returns a 400 error that names the unknown field.

What does Bulk Company Enrichment return?

Bulk Company Enrichment returns a JSON array. The array holds one object for each company that the data provider resolves. Each object carries the same fields as a Company Enrichment API response.

The following example shows the response to a request that carried four company IDs. The data provider resolved three of the four companies, so the array holds three objects. The values in the example are illustrative.

[
  {
    "url": "https://www.linkedin.com/company/microsoft",
    "name": "Microsoft",
    "universalName": "microsoft",
    "description": "Every company has a mission. What is ours? To empower every person and every organization on the planet to achieve more.",
    "followers": 22500000,
    "type": "Public Company"
  },
  {
    "url": "https://www.linkedin.com/company/shopify",
    "name": "Shopify",
    "universalName": "shopify",
    "description": "Shopify gives merchants the tools to start, grow, market and manage a retail business of any size.",
    "followers": 1420000,
    "type": "Public Company"
  },
  {
    "url": "https://www.linkedin.com/company/northwind-logistics",
    "name": "Northwind Logistics",
    "universalName": "northwind-logistics",
    "description": "Freight forwarding and warehouse capacity for mid-market manufacturers across Europe.",
    "followers": 8400,
    "type": "Privately Held"
  }
]

What does each Bulk Company Enrichment response field mean?

Field	Type	Description
`[]`	array	The top level of the response. One object per company returned.
`url`	string	The LinkedIn company page URL.
`name`	string	The company name as shown on LinkedIn.
`universalName`	string	The LinkedIn universal name of the company, that is the slug in the URL.
`description`	string	The company description from the LinkedIn About section.
`followers`	integer	The number of LinkedIn followers of the company page.
`type`	string	The company type as shown on LinkedIn, for example `Public Company`.

Is Bulk Company Enrichment synchronous or asynchronous?

Bulk Company Enrichment is synchronous. The endpoint returns every company in the same response. The endpoint returns no job identifier, so no second call is needed. A batch of 50 companies takes longer than a single company call. Set a client timeout that covers the whole batch.

How does Bulk Company Enrichment report a company that fails?

Bulk Company Enrichment reports a failure inside a batch by omission. The response array holds one object for each company that the data provider resolves. A company ID that the provider does not resolve produces no object and no error entry. The request still returns 200. Compare the length of the response array against the number of company IDs that you sent. If the two numbers differ, the difference is the number of company IDs that failed. To find which company IDs failed, send the same IDs again in smaller batches.

How much does Bulk Company Enrichment cost?

Bulk Company Enrichment costs 1 credit for each company returned. You pay per company returned, not per company ID sent. One credit costs $0.02 on the 1,000 and 5,000 credit packs. Larger packs cost less per credit. A full batch of 50 companies costs 50 credits, and 50 credits cost $1.00. If you send 50 company IDs and the response holds 46 companies, RichAPI charges 46 credits, which cost $0.92.

Companies returned	Credits	Cost
1	1	$0.02
46	46	$0.92
50	50	$1.00
500	500	$10.00
1,000	1,000	$20.00
10,000	10,000	$200.00

At the start of each Bulk Company Enrichment request, RichAPI holds 1 credit for each company ID in urns, up to 50 credits. A batch of 10 company IDs holds 10 credits. After the response, RichAPI charges 1 credit per company in the array and releases the rest of the hold. If the organization's credit balance is under the hold, the request returns 402 and no company is enriched.

RichAPI charges credits only for a successful call. A non-2xx response releases the whole hold and costs no credit.

How to enrich 500 companies in batches of 50

Split the list of 500 company IDs into ten batches of 50 company IDs.
Send one request per batch to https://api.richapi.ai/api/v1/enrich_companies_bulk.
Add the response array of each batch to one result list.
Compare the total count of returned companies against 500.

Company IDs in the list: 500
Maximum batch size: 50
Requests to send: 10
Maximum companies returned: 500
Credits charged: 500
Total cost: $10.00

Ten batches of 50 companies cost 10 × 50 = 500 credits. 500 credits at $0.02 each cost $10.00. If 25 company IDs across the ten batches fail, the response arrays hold 475 companies in total. RichAPI then charges 475 credits, which cost $9.50.

import requests

API_URL = "https://api.richapi.ai/api/v1/enrich_companies_bulk"
BATCH_SIZE = 50

# Replace this list with your own 500 numeric LinkedIn company IDs.
company_ids = ["1586"] * 500

companies = []
for start in range(0, len(company_ids), BATCH_SIZE):
    batch = company_ids[start:start + BATCH_SIZE]
    response = requests.post(
        API_URL,
        headers={"x-api-key": "YOUR_API_KEY"},
        json={"urns": batch},
        timeout=120,
    )
    response.raise_for_status()
    returned = response.json()
    companies.extend(returned)
    print("batch", start // BATCH_SIZE + 1, "sent", len(batch), "returned", len(returned))

print("total companies:", len(companies))
print("credits charged:", len(companies))
print("cost in dollars:", round(len(companies) * 0.02, 2))

What errors does Bulk Company Enrichment return?

An error response holds an error field with a text message.

Status	Meaning	What to do
`400`	The request body failed validation, or it holds an unknown field.	Correct the field that the message names. Send only the `urns` parameter.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	`Insufficient credits`: the organization has too few credits for the hold of 1 credit per company ID sent. Or `Monthly spend limit reached`: the team hit its monthly spend limit.	Buy credits in the RichAPI dashboard, or ask the organization owner to raise the spend limit, then send the request again.
`403`	`Endpoint not available on your plan`: this API key has no access to this endpoint.	Call `GET /api/v1/my-endpoints` to list the endpoints this key can use. Contact support for access.
`404`	The endpoint name is wrong.	Send the request to `/enrich_companies_bulk`.
`405`	The request used a method other than `POST`.	Send the request with the `POST` method.
`429`	Rate limit exceeded (too many requests per second).	Wait for the `Retry-After` seconds, then retry the request.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.
`502`	The upstream data provider failed.	Send the request again after a short wait.
`504`	The upstream data provider timed out.	Send a smaller batch, then send the request again.

For a retry loop, wait 1 second, then 2 seconds, then 4 seconds between attempts.

Frequently asked questions

How many companies can the Bulk Company Enrichment API enrich in one call?

The Bulk Company Enrichment API enriches up to 50 LinkedIn companies in one call. For a list of 500 companies, send ten requests of 50 company IDs each.

Does the Bulk Company Enrichment API charge for a company that it does not return?

No. The Bulk Company Enrichment API charges 1 credit for each company in the response array. A company ID that the data provider does not resolve is left out of the array and costs no credit.

Is the Bulk Company Enrichment API cheaper than the Company Enrichment API?

The price per company is the same. Both endpoints cost 1 credit per company. Bulk Company Enrichment replaces 50 requests with one request, so it cuts request count and total time.

Which parameters does the Bulk Company Enrichment API accept?

The Bulk Company Enrichment API accepts one parameter, urns. Any other field in the request body returns a 400 error that names the unknown field.

Where do I find a numeric LinkedIn company ID for the Bulk Company Enrichment API?

LinkedIn Company Search API returns the numeric LinkedIn company ID in the elements[].id field. That value goes straight into the urns array. The urns array takes the ID as a string, for example "1586".

Does the Bulk Company Enrichment API accept a LinkedIn company URL?

No. The Bulk Company Enrichment API accepts numeric LinkedIn company IDs in the urns array. To enrich a company from its LinkedIn URL, send Company Enrichment API.

Is the Bulk Company Enrichment API synchronous?

Yes. The Bulk Company Enrichment API returns every company in the same response. The endpoint needs no polling call and no webhook.

How do I enrich many LinkedIn people at once?

Send Bulk Profile Enrichment API. That endpoint takes up to 50 LinkedIn entity URNs per request.