SignalShelf · Developer documentation

LinkedIn profile

Sample profile responses are available. LinkedIn live company-page requests are disabled in production pending written source authorization and independent review.

Request

POST /api/v1/profiles · authenticate with the x-api-key header.

Parameter	Type	Required	Description
`platform`	string	Yes	"linkedin"
`handle`	string	Yes	Company page slug from linkedin.com/company/<slug>.
`mode`	string	No	"live" for real data, "demo" for a free labeled sample. Default "demo".
`freshness`	string	No	Oldest cached result you accept: "1h", "24h" (default), "7d", or "live" to force a refresh.

REQUEST EXAMPLE

curl "$SIGNALSHELF_BASE_URL/api/v1/profiles" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SIGNALSHELF_API_KEY" \
  --data '{"platform":"linkedin","handle":"google","mode":"demo","freshness":"24h"}'

const response = await fetch(`${process.env.SIGNALSHELF_BASE_URL}/api/v1/profiles`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.SIGNALSHELF_API_KEY },
  body: JSON.stringify({platform: "linkedin", handle: "google", mode: "demo", freshness: "24h"}),
});
const { data, meta } = await response.json();

import os, requests

response = requests.post(
    f"{os.environ['SIGNALSHELF_BASE_URL']}/api/v1/profiles",
    headers={"x-api-key": os.environ["SIGNALSHELF_API_KEY"]},
    json={"platform":"linkedin","handle":"google","mode":"demo","freshness":"24h"},
    timeout=30,
)
data = response.json()["data"]

Example response

Labeled sample fixture. Values are illustrative and do not describe a real creator.

EXAMPLE

{
  "data": {
    "platform": "linkedin",
    "handle": "google",
    "name": "Sample creator",
    "bio": "Illustrative sample data for exploring SignalShelf. Not a real profile lookup.",
    "followers": 128400,
    "following": 842,
    "posts": 326,
    "verified": false,
    "url": "https://www.linkedin.com/company/google/",
    "avatar": null,
    "sample": true,
    "provider": "sample-fixture",
    "details": {
      "entity": null,
      "industry": null,
      "company_size": null,
      "employees_on_linkedin": null,
      "headquarters": null,
      "type": null,
      "specialties": [],
      "address": null
    }
  },
  "meta": {
    "event_id": "sample",
    "mode": "demo",
    "cache": "SAMPLE",
    "credits_charged": 0,
    "fetched_at": null,
    "age_seconds": null,
    "duration_ms": 0
  }
}

Profile fields

Every platform returns these fields. Fields a platform does not expose are null (or [] for links); they are never guessed.

Field	Type	Description
`platform`	string	Platform you requested.
`handle`	string	Normalized handle (lowercase, no @).
`name`	string	Display name.
`bio`	string	Profile description, as shown publicly.
`followers`	number	Follower or subscriber count.
`following`	number	Accounts this profile follows.
`posts`	number	Total posts, videos, pins or repositories, depending on platform.
`verified`	boolean	Platform verification badge, when exposed.
`url`	string	Canonical public profile URL.
`avatar`	string \| null	Profile picture URL (largest available).
`sample`	boolean	Always false for live data; true only in sample mode.
`provider`	string	Engine that produced the data.
`details`	object	Platform-specific fields, listed below.

LinkedIn-specific fields (details)

Returned inside data.details.

Field	Type	Description
`details.entity`	string \| null	Always "company".
`details.industry`	string \| null	Industry.
`details.company_size`	string \| null	Size band shown on the page.
`details.employees_on_linkedin`	string \| null	Employees with LinkedIn profiles.
`details.headquarters`	string \| null	Headquarters city.
`details.type`	string \| null	Company type (e.g. Public Company).
`details.specialties`	array	Listed specialties.
`details.address`	string \| null	Postal address { street, city, region, postal_code, country }.

Response metadata

Field	Type	Description
`meta.cache`	string	HIT (served from cache, 0 credits), MISS (fresh fetch) or SAMPLE.
`meta.credits_charged`	number	Credits charged for this request.
`meta.fetched_at`	string	When the data was fetched from the source.
`meta.age_seconds`	number	Age of the data at response time.
`meta.duration_ms`	number	Server processing time.

Errors

Every failure is free: reserved credits are refunded automatically.

Field	Type	Description
`404 PROFILE_NOT_FOUND`	error	The profile does not exist publicly.
`422 PROFILE_UNAVAILABLE`	error	The source did not expose even the public profile fields for this account.
`503 SOURCE_NOT_AUTHORIZED`	error	Live access for this platform is disabled in production pending source authorization. No credits are charged.
`503 SOURCE_AUTH_REQUIRED`	error	The source demanded a login for this request. Retry later.
`503 UPSTREAM_RATE_LIMITED`	error	The source is rate limiting. Retry after the Retry-After header.
`402 INSUFFICIENT_CREDITS`	error	Not enough credits for a fresh lookup. Cached and sample results stay free.

Limitations

LinkedIn live company-page requests are disabled in production pending written source authorization and independent review.

LinkedIn live company-page requests are disabled in production until written source authorization and an independent review are complete.

Local parser tests and successful page reads do not grant permission to commercialize a source method.

Company pages only. Personal LinkedIn profiles require sign-in and are not supported.

Explore the API in your workspace. Sample results and accepted cache hits cost zero credits. Open the playground →