Skip to main content

Social Links Finder API

Written by Kadri - RichAPI Support Team

POST /web_social_links • Credits: 1 credit per call

Social Links Finder scans one website URL and returns the social media profile links on that page. The response holds a data.links object that groups the found URLs by platform name, and a meta object with the timing of the call. Each call costs 1 credit.

What does Social Links Finder do?

A company website almost always links to the social profiles of the company. Those links sit in the footer, in the header or in a share widget. Social Links Finder reads the page HTML and pulls out every social profile URL that it finds. The endpoint matches ten platforms and groups the URLs under the name of each platform. One platform can hold several URLs, so every value is an array. One call covers one URL.

Which endpoint does Social Links Finder use?

  • Method:POST

  • URL:https://api.richapi.ai/api/v1/web_social_links

  • Authentication:x-api-key header

  • Response: Synchronous JSON

  • Credits: 1 credit per call

How to send a Social Links Finder request

  1. Copy your API key from the RichAPI dashboard.

  2. Set the url parameter to the full website URL.

  3. To accept a cached result, set the cache parameter to true.

  4. Send a POST request to https://api.richapi.ai/api/v1/web_social_links.

  5. Send the API key in the x-api-key header.

  6. Read the platform that you need from the data.links object.

CAUTION: Each Social Links Finder call costs 1 credit. A page with no social links also costs 1 credit.

cURL

curl -X POST https://api.richapi.ai/api/v1/web_social_links   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "url": "https://hubspot.com",
    "cache": true
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/web_social_links",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "url": "https://hubspot.com",
        "cache": True,
    },
    timeout=60,
)
response.raise_for_status()
links = response.json()["data"]["links"]
print(links.get("linkedin", []))

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/web_social_links", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hubspot.com",
    cache: true,
  }),
});

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

Which parameters does Social Links Finder accept?

Parameter

Type

Required

Default

Description

url

string

Yes

None

The website URL to scan for social links. Send a full HTTP or HTTPS URL.

cache

boolean

No

false

Set to true to accept a cached result. Set to false to scan the live page.

What does Social Links Finder return?

The block below is an example response for https://hubspot.com. The field names and the structure are exact. The URL values and the timings are illustrative.

{
  "data": {
    "links": {
      "facebook": ["https://www.facebook.com/hubspot"],
      "twitter": ["https://twitter.com/HubSpot"],
      "linkedin": ["https://www.linkedin.com/company/hubspot"],
      "instagram": ["https://www.instagram.com/hubspot"],
      "youtube": ["https://www.youtube.com/user/HubSpot"],
      "tiktok": ["https://www.tiktok.com/@hubspot"],
      "github": ["https://github.com/HubSpot"]
    }
  },
  "meta": {
    "cache_hit": false,
    "execution_time_ms": 1842,
    "quality_warning": null
  }
}

The example page carries no Pinterest, Reddit or Discord link, so data.links holds no key for those three platforms.

Which fields does the Social Links Finder response hold?

Field

Type

Description

data

object

The result of the scan.

data.links

object

The found profile URLs, grouped by platform name. The object holds one key per detected platform.

data.links.<platform>

array of strings

Every unique URL that the scan found for that platform.

meta

object

The metadata of the call.

meta.cache_hit

boolean

The value is true for a result served from the cache.

meta.execution_time_ms

integer

The duration of the call, in milliseconds.

meta.quality_warning

string or null

A note about a scan that returned no data. The value is null for a normal scan.

Which social networks does Social Links Finder detect?

Social Links Finder matches ten platforms. Each platform name becomes a key inside the data.links object. The twitter key covers both a twitter.com link and an x.com link.

Key in data.links

Platform

A matched link looks like

facebook

Facebook

https://www.facebook.com/hubspot

twitter

Twitter / X

https://twitter.com/HubSpot

linkedin

LinkedIn

https://www.linkedin.com/company/hubspot

instagram

Instagram

https://www.instagram.com/hubspot

youtube

YouTube

https://www.youtube.com/user/HubSpot

tiktok

TikTok

https://www.tiktok.com/@hubspot

pinterest

Pinterest

https://www.pinterest.com/hubspot

reddit

Reddit

https://www.reddit.com/r/hubspot

github

GitHub

https://github.com/HubSpot

discord

Discord

https://discord.gg/hubspot

The linkedin key matches a personal profile URL, a company URL, a school URL and a showcase URL.

What does the response hold for an absent platform?

Social Links Finder adds a key to data.links only for a platform with at least one match on the page. If the page holds no TikTok link, the data.links object holds no tiktok key. The key is absent, not null. Read each platform with a safe lookup, such as data.links.get("tiktok", []) in Python.

If the page holds no social link at all, data.links is an empty object. The meta.quality_warning field then holds the text Page returned no relevant data.

CAUTION: Do not treat an absent key as a failure. A response with two platforms and a response with ten platforms both cost 1 credit.

How do you enrich a company record from its website?

Many CRM records hold a company website and nothing else. Social Links Finder turns that one website into a set of profile URLs. The linkedin key is the useful one, because Company Enrichment accepts a LinkedIn company URL as its input. Two calls take a bare domain to a full company record.

  1. Send a Social Links Finder request with the company website as url.

  2. Read the first value of data.links.linkedin from the response.

  3. Send that LinkedIn URL to the Company Enrichment endpoint.

  4. Store the name, industry, company size and headquarters from the enrichment response.

  5. Store the other social URLs against the same company record.

The two calls cost 2 credits in total, or $0.04 per company.

How much does Social Links Finder cost?

Social Links Finder costs 1 credit per call. 1 credit costs $0.02 on the 1,000 and 5,000 credit packs, and less on larger packs. The table uses $0.02. The credit count does not change with the number of links that the scan finds.

Calls

Credits

Cost

1

1

$0.02

100

100

$2.00

1,000

1,000

$20.00

10,000

10,000

$200.00

Which errors can Social Links Finder return?

Status

Meaning

What to do

400

The request body failed validation.

Correct the parameter that the message names. Send a full HTTP or HTTPS URL.

401

The API key is missing, wrong or revoked.

Send a valid key in the x-api-key header.

402

The organization has no credits left, or the team reached its monthly spend limit.

Buy credits in the RichAPI dashboard.

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. For access, write to [email protected].

404

The endpoint name is wrong.

Send the request to /web_social_links.

405

The request used a method other than POST.

Send the request again with the POST method.

422

The service could not process a value, for example a URL that does not start with http:// or https://, or a private network address.

Send a full public HTTP or HTTPS URL.

429

The request rate is over the limit.

Wait, then send the request again. For a higher limit, write to [email protected].

500

The API failed.

Send the request again. If the failure repeats, write to [email protected].

502

The target website did not answer.

Wait a few seconds, then send the request again.

RichAPI charges no credit for a 400, 401, 402, 403, 404, 405, 422, 429, 500 or 502 response.

Frequently asked questions

Which social networks does Social Links Finder detect?

Social Links Finder detects ten platforms: Facebook, Twitter, LinkedIn, Instagram, YouTube, TikTok, Pinterest, Reddit, GitHub and Discord. The response groups the found URLs by platform name inside the data.links object.

What does the response hold for a page with no LinkedIn link?

Social Links Finder adds a key only for a platform that appears on the page. If the page holds no LinkedIn link, data.links holds no linkedin key, and the call still costs 1 credit.

Why is each value an array and not a single URL?

One page often links to several profiles of the same platform, such as a company page and a careers page. Social Links Finder returns every unique URL per platform, so each value is an array of strings.

Does Social Links Finder scan more than one page?

No. One Social Links Finder call scans one URL. Most companies link to their social profiles from the home page footer, so the home page URL is the best input.

Can Social Links Finder find the LinkedIn company page for a domain?

Yes, for a website that links to its own LinkedIn page. Send the website URL, then read the first value of data.links.linkedin. Pass that URL to the Company Enrichment endpoint to get the firmographics of the company.

How long does Social Links Finder cache a result?

Social Links Finder caches a scan for 12 hours. To accept a cached result inside that window, set cache to true. The meta.cache_hit field reports the source. A cached call and a live call both cost 1 credit.

Does Social Links Finder need a login or a cookie?

No. Social Links Finder accepts no login credentials and no cookies. It reads only a page that a public visitor can open.

What is the difference between Social Links Finder and Web Scraper?

Social Links Finder returns the social profile URLs as structured fields for 1 credit. Web Scraper returns the whole page as HTML and markdown, and your code must parse the links.

Related articles

Did this answer your question?
RichAPI - B2B GTM APIs