POST /enrich_profiles_bulk • Credits: 1 credit per profile returned

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

What does Bulk Profile Enrichment do?

Growth teams hold long lists of LinkedIn entity URNs without profile data. One call per person is slow at list scale. Bulk Profile Enrichment reads up to 50 LinkedIn person profiles in a single request. The data source is LinkedIn. The endpoint returns the profiles in one array in the same response. For a single person, send Profile Enrichment API instead.

Which endpoint does Bulk Profile Enrichment use?

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

How to send a Bulk Profile Enrichment request

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

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

cURL

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

Python

import requests

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

Node.js

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

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

What parameters does Bulk Profile Enrichment accept?

Parameter	Type	Required	Default	Description
`urns`	array of strings	Yes	`[]`	The LinkedIn entity URNs of the people, for example `ACoAAAGhXV8B9jFBu7w3NLhsepBqpzJ1FdGgkuA`. Maximum 50 per request.

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

What does Bulk Profile Enrichment return?

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

The following example shows the response to a request that carried four URNs. The data provider resolved three of the four people, so the array holds three objects. The names in the example are fictional.

[
  {
    "url": "https://www.linkedin.com/in/dana-whitfield-revops",
    "firstname": "Dana",
    "lastname": "Whitfield",
    "headline": "Head of Revenue Operations at Northwind Logistics",
    "summary": "I build the reporting layer that connects pipeline data to freight capacity. 12 years in logistics operations.",
    "picture": "https://media.licdn.com/dms/image/v2/C4D03AQH1x8mVw9k2Zg/profile-displayphoto-shrink_400_400/0/1712793600",
    "industry": "Transportation, Logistics, Supply Chain and Storage",
    "location": {}
  },
  {
    "url": "https://www.linkedin.com/in/marco-ferreira-eng",
    "firstname": "Marco",
    "lastname": "Ferreira",
    "headline": "Senior Backend Engineer at Larkfield Systems",
    "summary": "Distributed systems and payments infrastructure. I write Go and Rust, and I care about queue latency.",
    "picture": "https://media.licdn.com/dms/image/v2/D5603AQGr7bTqL0nYpA/profile-displayphoto-shrink_400_400/0/1705276800",
    "industry": "Software Development",
    "location": {}
  },
  {
    "url": "https://www.linkedin.com/in/priya-raghunathan-tessellate",
    "firstname": "Priya",
    "lastname": "Raghunathan",
    "headline": "Founder and CEO at Tessellate Health",
    "summary": "We give small clinics the scheduling tools that large hospital groups take for granted.",
    "picture": "https://media.licdn.com/dms/image/v2/D4E03AQKm2pQvXsN8Rw/profile-displayphoto-shrink_400_400/0/1719792000",
    "industry": "Hospital and Health Care",
    "location": {}
  }
]

What does each Bulk Profile Enrichment response field mean?

Field	Type	Description
`[]`	array	The top level of the response. One object per profile returned.
`url`	string	The LinkedIn profile URL of the person.
`firstname`	string	The first name of the person.
`lastname`	string	The last name of the person.
`headline`	string	The LinkedIn headline of the person.
`summary`	string	The About text of the LinkedIn profile.
`picture`	string	The URL of the profile picture.
`industry`	string	The LinkedIn industry classification of the person.
`location`	object	The location of the person. The API reference names no key inside this object, so the example above shows it empty.

Is Bulk Profile Enrichment synchronous or asynchronous?

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

How does Bulk Profile Enrichment report a profile that fails?

Bulk Profile Enrichment reports a failure inside a batch by omission. The response array holds one object for each profile that the data provider resolves. A URN 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 URNs that you sent. If the two numbers differ, the difference is the number of URNs that failed. To find which URNs failed, send the same URNs again in smaller batches.

How much does Bulk Profile Enrichment cost?

Bulk Profile Enrichment costs 1 credit for each profile returned. You pay per profile returned, not per URN 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 profiles costs 50 credits, and 50 credits cost $1.00. If you send 50 URNs and the response holds 47 profiles, RichAPI charges 47 credits, which cost $0.94.

Profiles returned	Credits	Cost
1	1	$0.02
47	47	$0.94
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 Profile Enrichment request, RichAPI holds 1 credit for each URN in urns, up to 50 credits. A batch of 10 URNs holds 10 credits. After the response, RichAPI charges 1 credit per profile 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 profile 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 profiles in batches of 50

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

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

Ten batches of 50 profiles cost 10 × 50 = 500 credits. 500 credits at $0.02 each cost $10.00. If 30 URNs across the ten batches fail, the response arrays hold 470 profiles in total. RichAPI then charges 470 credits, which cost $9.40.

import requests

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

# Replace this list with your own 500 LinkedIn entity URNs.
urns = ["ACoAAAGhXV8B9jFBu7w3NLhsepBqpzJ1FdGgkuA"] * 500

profiles = []
for start in range(0, len(urns), BATCH_SIZE):
    batch = urns[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()
    profiles.extend(returned)
    print("batch", start // BATCH_SIZE + 1, "sent", len(batch), "returned", len(returned))

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

What errors does Bulk Profile 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 URN 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_profiles_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 profiles can the Bulk Profile Enrichment API enrich in one call?

The Bulk Profile Enrichment API enriches up to 50 LinkedIn profiles in one call. For a list of 500 profiles, send ten requests of 50 URNs each.

Does the Bulk Profile Enrichment API charge for a profile that it does not return?

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

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

The price per profile is the same: 1 credit. Profile Enrichment adds 1 credit when you set include_social_metrics to true and the metrics are available. Bulk Profile Enrichment replaces 50 requests with one request, so it cuts request count and total time.

Which parameters does the Bulk Profile Enrichment API accept?

The Bulk Profile 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 LinkedIn entity URN for the Bulk Profile Enrichment API?

A LinkedIn entity URN starts with ACoA. Profile Enrichment API returns the entityUrn of a person, and that value goes straight into the urns array.

Is the Bulk Profile Enrichment API synchronous?

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

How do I enrich many LinkedIn companies at once?

Send Bulk Company Enrichment API. That endpoint takes up to 50 numeric LinkedIn company IDs per request.