Name: Social Links Finder API: Company Social Profiles by Domain
Brand: compasslab-1
SKU: api-compasslab-1-social-links-finder
Availability: InStock
Author: API Market

WPTOOLS

# Social Links Finder API

## Overview

The Social Links Finder API takes a company's domain and returns the official social media profiles that the company links as its own. It has 2 endpoints. `/v1/social-links` checks one domain: it reads the homepage and up to two about or contact pages and returns profiles on LinkedIn (company pages), X, Facebook, Instagram, YouTube, TikTok, GitHub, Pinterest, Threads, Bluesky, Mastodon, Discord, Telegram and Xing, together with the company name and a logo URL. `/v1/social-links/batch` does the same for up to 5 domains in parallel and counts as one request; each domain gets its own result and status, so one unreachable site never fails the batch.

It is built for CRM and lead enrichment, sales and marketing teams researching companies, brand monitoring and competitor research, and directories or marketplaces that show each vendor's logo and official channels. A profile counts only when the site links it from its header, footer, navigation or a social block, or lists it in schema.org `sameAs`; links in body text, share buttons and personal profiles are left out. Each profile comes with its `network`, normalised `url`, `handle`, the `source_url` it was found on, the `source_type`, a `confidence` score from 0 to 1 and `pages_found_on`. Each result also carries a `status`, the `pages_checked` with their outcome, a count of `personal_profiles_omitted`, `warnings` and a `metadata` block with the fetch time and elapsed milliseconds.

## Features

*   **2 endpoints**: Single-domain lookup and a batch lookup for up to 5 domains.
*   **Simple input**: A bare domain such as `stripe.com` or a full website URL such as `https://www.example.com`.
*   **14 networks**: LinkedIn, X, Facebook, Instagram, YouTube, TikTok, GitHub, Pinterest, Threads, Bluesky, Mastodon, Discord, Telegram and Xing.
*   **Company profiles only**: LinkedIn results are company, school or showcase pages. Personal profiles such as `linkedin.com/in/` are never returned, only counted in `personal_profiles_omitted`.
*   **Data source and method**: The homepage and up to two about or contact pages of the site, reading header, footer, navigation and social-block links and schema.org `sameAs` data. robots.txt is respected.
*   **Clean URLs**: Tracking parameters are removed, twitter.com is shown as x.com and duplicates are merged.
*   **Company name and logo**: The name comes from schema.org Organization data, `og:site_name` or the page title; the logo from schema.org, `og:image` or the apple-touch-icon.
*   **Rate limit**: 1 request per second on FREE, 5 on PRO, 10 on ULTRA and 20 on MEGA.

## Use Cases

*   **CRM and lead enrichment**: Add LinkedIn, X and other channels plus a logo to each company record from its domain.
*   **Sales prospecting**: Find a prospect's LinkedIn company page and other channels before outreach.
*   **Brand monitoring**: Collect the official accounts of your own brand and of competitors to track them.
*   **Partner and influencer research**: Find the official channels of B2B partners and vendors in bulk with the batch endpoint.
*   **Directories and marketplaces**: Show each vendor's logo and official social links next to its listing.
*   **Data cleaning**: Check that the social links stored for a company are the ones its own site links.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/compasslab-1/social-links-finder
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Find social links for a domain

Returns the official social media profiles a company links from its own site, with handles, the company name and a logo URL. Profiles are listed best first. `status` is `ok` when at least one company profile was found, `no_profiles_found` when the site was read but links none, or a value such as `blocked_by_robots`, `blocked_by_site`, `not_found`, `dead_link`, `timeout` or `fetch_failed` when the homepage could not be read.

**Method:** `GET`

**Endpoint:** `/v1/social-links`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `domain` | query | Domain or website URL, for example `example.com` or `https://www.example.com` (minimum 3 characters). | string | Yes | - | 253 characters |
| `include_handles` | query | Also return each account's handle. | boolean | No | `true` | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/social-links-finder/v1/social-links?domain=stripe.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "domain": "stripe.com",
  "status": "ok",
  "error": null,
  "company_name": "Stripe",
  "logo_url": "https://images.stripeassets.com/fzn2n1nzq965/1hgcBNd12BfT9VLgbId7By/01d91920114b124fb4cf6d448f9f06eb/favicon.svg",
  "profiles": [
    {
      "network": "github",
      "url": "https://github.com/stripe",
      "handle": "@stripe",
      "source_url": "https://stripe.com/en-de",
      "source_type": "structured_data",
      "confidence": 0.97,
      "pages_found_on": 1
    },
    {
      "network": "facebook",
      "url": "https://www.facebook.com/StripeHQ",
      "handle": "StripeHQ",
      "source_url": "https://stripe.com/en-de",
      "source_type": "structured_data",
      "confidence": 0.97,
      "pages_found_on": 1
    },
    {
      "network": "instagram",
      "url": "https://www.instagram.com/stripehq",
      "handle": "@stripehq",
      "source_url": "https://stripe.com/en-de",
      "source_type": "structured_data",
      "confidence": 0.97,
      "pages_found_on": 1
    },
    {
      "network": "linkedin",
      "url": "https://www.linkedin.com/company/stripe",
      "handle": "stripe",
      "source_url": "https://stripe.com/en-de",
      "source_type": "structured_data",
      "confidence": 0.97,
      "pages_found_on": 1
    },
    {
      "network": "x",
      "url": "https://x.com/stripe",
      "handle": "@stripe",
      "source_url": "https://stripe.com/en-de",
      "source_type": "structured_data",
      "confidence": 0.97,
      "pages_found_on": 1
    },
    {
      "network": "youtube",
      "url": "https://youtube.com/@StripeDev",
      "handle": "@StripeDev",
      "source_url": "https://stripe.com/en-de",
      "source_type": "structured_data",
      "confidence": 0.97,
      "pages_found_on": 1
    },
    {
      "network": "youtube",
      "url": "https://youtube.com/@stripe",
      "handle": "@stripe",
      "source_url": "https://stripe.com/en-de",
      "source_type": "structured_data",
      "confidence": 0.97,
      "pages_found_on": 1
    }
  ],
  "pages_checked": [
    {
      "url": "https://stripe.com/en-de",
      "kind": "home",
      "status": "ok"
    },
    {
      "url": "https://stripe.com/en-de/contact/sales",
      "kind": "contact",
      "status": "ok"
    },
    {
      "url": "https://stripe.com/en-de/about",
      "kind": "about",
      "status": "ok"
    }
  ],
  "personal_profiles_omitted": 0,
  "warnings": [],
  "metadata": {
    "fetched_at": "2026-10-17T14:55:00Z",
    "elapsed_ms": 1627,
    "cached": false
  }
}
```

#### 2. Find social links for up to 5 domains

Runs the same lookup for 1 to 5 domains in parallel and returns one result per domain, in the same order as the request. Each result has its own `status`, so one unreachable site does not fail the batch. `ok` is the number of domains with at least one profile. A batch counts as one request.

**Method:** `POST`

**Endpoint:** `/v1/social-links/batch`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `domains` | body | List of domains or website URLs, each 3 to 253 characters (minimum 1). | array of strings | Yes | - | 5 domains |
| `include_handles` | body | Also return each account's handle. | boolean | No | `true` | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/compasslab-1/social-links-finder/v1/social-links/batch" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["github.com", "notion.so"]}'
```

**Example Response (200 OK):**

```json
{
  "count": 2,
  "ok": 2,
  "results": [
    {
      "domain": "github.com",
      "status": "ok",
      "error": null,
      "company_name": "GitHub",
      "logo_url": "https://images.ctfassets.net/8aevphvgewt8/4pe4eOtUJ0ARpZRE4fNekf/f52b1f9c52f059a33170229883731ed0/GH-Homepage-Universe-img.png",
      "profiles": [
        {
          "network": "instagram",
          "url": "https://www.instagram.com/github",
          "handle": "@github",
          "source_url": "https://github.com/",
          "source_type": "link",
          "confidence": 0.94,
          "pages_found_on": 3
        },
        {
          "network": "linkedin",
          "url": "https://www.linkedin.com/company/github",
          "handle": "github",
          "source_url": "https://github.com/",
          "source_type": "link",
          "confidence": 0.94,
          "pages_found_on": 3
        },
        {
          "network": "tiktok",
          "url": "https://www.tiktok.com/@github",
          "handle": "@github",
          "source_url": "https://github.com/",
          "source_type": "link",
          "confidence": 0.94,
          "pages_found_on": 3
        },
        {
          "network": "x",
          "url": "https://x.com/github",
          "handle": "@github",
          "source_url": "https://github.com/",
          "source_type": "link",
          "confidence": 0.94,
          "pages_found_on": 3
        }
      ],
      "pages_checked": [
        {
          "url": "https://github.com/",
          "kind": "home",
          "status": "ok"
        },
        {
          "url": "https://github.com/team",
          "kind": "about",
          "status": "ok"
        },
        {
          "url": "https://github.com/about",
          "kind": "about",
          "status": "ok"
        }
      ],
      "personal_profiles_omitted": 0,
      "warnings": [],
      "metadata": {
        "fetched_at": "2026-10-17T14:55:04Z",
        "elapsed_ms": 1385,
        "cached": false
      }
    },
    {
      "domain": "notion.so",
      "status": "ok",
      "error": null,
      "company_name": "Notion",
      "logo_url": "https://www.notion.com/front-static/logo-ios.png",
      "profiles": [
        {
          "network": "facebook",
          "url": "https://www.facebook.com/NotionHQ",
          "handle": "NotionHQ",
          "source_url": "https://www.notion.com/",
          "source_type": "structured_data",
          "confidence": 0.97,
          "pages_found_on": 1
        },
        {
          "network": "instagram",
          "url": "https://www.instagram.com/notionhq",
          "handle": "@notionhq",
          "source_url": "https://www.notion.com/",
          "source_type": "structured_data",
          "confidence": 0.97,
          "pages_found_on": 1
        },
        {
          "network": "linkedin",
          "url": "https://www.linkedin.com/company/notionhq",
          "handle": "notionhq",
          "source_url": "https://www.notion.com/",
          "source_type": "structured_data",
          "confidence": 0.97,
          "pages_found_on": 1
        },
        {
          "network": "youtube",
          "url": "https://www.youtube.com/channel/UCoSvlWS5XcwaSzIcbuJ-Ysg",
          "handle": "channel/UCoSvlWS5XcwaSzIcbuJ-Ysg",
          "source_url": "https://www.notion.com/",
          "source_type": "structured_data",
          "confidence": 0.97,
          "pages_found_on": 1
        },
        {
          "network": "x",
          "url": "https://x.com/NotionHQ",
          "handle": "@NotionHQ",
          "source_url": "https://www.notion.com/",
          "source_type": "structured_data",
          "confidence": 0.97,
          "pages_found_on": 1
        }
      ],
      "pages_checked": [
        {
          "url": "https://www.notion.com/",
          "kind": "home",
          "status": "ok"
        },
        {
          "url": "https://www.notion.com/contact-sales",
          "kind": "contact",
          "status": "ok"
        },
        {
          "url": "https://www.notion.com/about",
          "kind": "about",
          "status": "ok"
        }
      ],
      "personal_profiles_omitted": 0,
      "warnings": [],
      "metadata": {
        "fetched_at": "2026-10-17T14:55:04Z",
        "elapsed_ms": 1668,
        "cached": false
      }
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request was processed. Check `status` in each result: a site that could not be read or links no company profile still returns `200` with a status such as `no_profiles_found`, `blocked_by_site` or `timeout`. |
| 400 | Bad Request | The input is invalid, for example a value that is not a usable domain or URL. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path does not exist. Check the path against the list above. |
| 422 | Unprocessable Entity | A parameter is missing or invalid, for example no `domain`, or more than 5 domains in a batch. The response says which one. |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit, or the FREE plan's calls are used up. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Each plan has its own per-second limit: FREE allows 1 request per second, PRO 5, ULTRA 10 and MEGA 20. FREE includes 50 calls and is a hard limit, so requests after the 50th return `429 Too Many Requests`. PRO (3,000 calls), ULTRA (15,000 calls) and MEGA (60,000 calls) are soft limits, so calls above the included amount are billed as overage instead of being blocked. A batch of up to 5 domains counts as one request. Requests above the per-second limit also return `429`. Back off before retrying and honour any `Retry-After` header. Each lookup fetches live pages from the target site; in our tests a single domain took about 1.6 seconds and the two-domain batch finished with per-domain times of 1.4 and 1.7 seconds.

## FAQ

**Will it return an employee's LinkedIn profile?**

No. Only LinkedIn company, school and showcase pages are returned. Personal profiles such as `linkedin.com/in/`, author boxes and staff cards are counted in `personal_profiles_omitted` and never returned.

**Why is a profile I know about missing?**

The API only returns profiles the site itself links in its header, footer, navigation or a social block, or lists in schema.org `sameAs`. Links in body text are ignored because they are usually partners, clients or press mentions, and share buttons are dropped. If the company does not link a profile from those places, it is not returned.

**What does the confidence score mean?**

It runs from 0 to 1. Profiles found in schema.org data score 0.97 and header or footer links score about 0.9, with a small bonus when the same profile appears on several checked pages. In our tests, Stripe's schema.org profiles scored 0.97 and GitHub's footer links, found on 3 pages, scored 0.94.

**What happens if a site blocks bots?**

The result comes back with `status: "blocked_by_site"` (or `blocked_by_robots` when robots.txt disallows it). The API respects robots.txt and only reads public pages.

**Can I get URLs without handles?**

Yes. Set `include_handles=false` on the GET endpoint, or `"include_handles": false` in the batch body, and the handles are left out.

**How well does it work on real companies?**

The seller reports that on 20 real company domains, 17 returned 2 or more official profiles, every profile checked by hand belonged to the company, and the median response time was 1.8 seconds.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Social links finder API: send a company domain and get its official LinkedIn, X, Instagram, YouTube, TikTok and GitHub profiles, with handles and logo URL.

Social Links Finder API: Company Social Profiles by Domain

FREE