REST API v1

Superdata offers seven focused products through one synchronous REST API: Social URL to Email, Email Lookup, Email Validation, Profile, Profile Posts, Company, and Company Posts. Every endpoint returns structured data directly and does not create background jobs or require polling.

Base URL and authentication

https://api.superdata.so

Every request requires an API key in the authorization header:

Authorization: Bearer YOUR_API_KEY

Create and revoke keys from the Superdata API dashboard. API keys are not accepted in query parameters.

Endpoints

View the complete Social URL to Email API reference →

POST /v1/email/find

Send one HTTPS social profile URL as JSON: {"social_url":"https://socialurl.com/in/example"}. The endpoint returns a work email only when the contact source marks it verified. The URL and email here are illustrative.

Look up an email

View the complete Email Lookup API reference →

POST /v1/email/lookup

Send one address as JSON: {"email":"alex@example.com"}. A match can return person and current employer data; partial and no-match results are labeled with data.match_status. This operation uses up to three credits, with the actual amount in meta.credits_used.

curl --request POST \
  --url 'https://api.superdata.so/v1/email/lookup' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"email":"alex@example.com"}'

Validate an email

View the complete Email Validation API reference →

POST /v1/email/validate

Send one address as JSON: {"email":"alex@example.com"}. The response includes a validity verdict, the domain catch-all signal, greylisting information, and meta.credits_used.

Get a profile

View the complete Profile API reference →

GET /v1/profile

Provide at least one identifier. When several are supplied, precedence is url, person.id, user_id, then profile_id.

Parameter	Type	Default	Description
`url`	URL	—	Public LinkedIn `/in/` or `/pub/` profile URL
`person.id`	positive integer	—	Numeric person ID accepted by Superdata; the dot is part of the parameter name
`user_id`	positive integer	—	LinkedIn user ID
`profile_id`	positive integer	—	LinkedIn profile ID
`strategy`	enum	`cached`	`cached`, `fetch`, `strict`, or `besteffort`
`maxage`	positive integer	—	Maximum cache age in seconds for `strict` or `besteffort`
`experience_filter`	enum	`default`	`default`, `current`, `revisions`, or `distincts`
`education_filter`	enum	`default`	`default`, `current`, `revisions`, or `distincts`
`summary_filter`	enum	`default`	`default` or `last_complete`

curl --request GET \
  --url "https://api.superdata.so/v1/profile?url=https%3A%2F%2Fwww.linkedin.com%2Fin%2Fsatyanadella&strategy=cached" \
  --header "Authorization: Bearer YOUR_API_KEY"

Get a company

View the complete Company API reference →

GET /v1/company

Provide at least one identifier. Precedence is url, company.id, then org_id.

Parameter	Type	Default	Description
`url`	URL	—	Public LinkedIn `/company/` or `/school/` URL
`company.id`	positive integer	—	Numeric company ID accepted by Superdata; the dot is part of the parameter name
`org_id`	positive integer	—	LinkedIn company or school ID
`strategy`	enum	`cached`	`cached`, `fetch`, `strict`, or `besteffort`
`maxage`	positive integer	—	Maximum cache age in seconds for `strict` or `besteffort`

curl --request GET \
  --url "https://api.superdata.so/v1/company?url=https%3A%2F%2Fwww.linkedin.com%2Fcompany%2Fmicrosoft&strategy=cached" \
  --header "Authorization: Bearer YOUR_API_KEY"

Get profile posts

View the complete Profile Posts API reference →

GET /v1/profile/posts

Provide url, person.id, or profile_id, in that precedence order.

Parameter	Type	Default	Description
`url`	URL	—	Public LinkedIn `/in/` or `/pub/` profile URL
`person.id`	positive integer	—	Numeric person ID accepted by Superdata
`profile_id`	positive integer	—	LinkedIn profile ID
`strategy`	enum	`cached`	`cached` or `fetch`
`sort_field`	enum	`id`	`id` or `post_date`
`offset`	integer	`0`	Result offset; minimum `0`
`page_size`	integer	`10`	Results per page; minimum `1`, maximum `100`

curl --request GET \
  --url "https://api.superdata.so/v1/profile/posts?url=https%3A%2F%2Fwww.linkedin.com%2Fin%2Fsatyanadella&page_size=10&sort_field=post_date" \
  --header "Authorization: Bearer YOUR_API_KEY"

Get company posts

View the complete Company Posts API reference →

GET /v1/company/posts

Provide url, company.id, or org_id, in that precedence order.

Parameter	Type	Default	Description
`url`	URL	—	Public LinkedIn `/company/` or `/school/` URL
`company.id`	positive integer	—	Numeric company ID accepted by Superdata
`org_id`	positive integer	—	LinkedIn company or school ID
`strategy`	enum	`cached`	`cached` or `fetch`
`sort_field`	enum	`id`	`id` or `post_date`
`offset`	integer	`0`	Result offset; minimum `0`
`page_size`	integer	`10`	Results per page; minimum `1`, maximum `100`

curl --request GET \
  --url "https://api.superdata.so/v1/company/posts?url=https%3A%2F%2Fwww.linkedin.com%2Fcompany%2Fmicrosoft&page_size=10&sort_field=post_date" \
  --header "Authorization: Bearer YOUR_API_KEY"

Cache strategies

Strategy	Behavior
`cached`	Return an available fresh cache result without fetching the source
`fetch`	Fetch a fresh result from the source
`strict`	Use cache only when it is newer than `maxage`; otherwise fetch fresh
`besteffort`	Use cache when newer than `maxage`; otherwise fetch and fall back to stale cache if the fetch fails

strict and besteffort are supported by Profile and Company. Post endpoints support cached and fetch.

Responses

A successful profile or company request returns the provider fields under data:

{
  "request_id": "req_01...",
  "data": {},
  "meta": {
    "source": "linkedin",
    "cached": false,
    "credits_used": 1
  }
}

Post responses include data.posts and pagination metadata. Additional provider fields remain under data.

{
  "request_id": "req_01...",
  "data": { "posts": [] },
  "meta": {
    "source": "linkedin",
    "cached": false,
    "credits_used": 1,
    "pagination": {
      "offset": 0,
      "page_size": 10,
      "next_offset": null,
      "has_more": false
    }
  }
}

Errors always use one safe envelope:

{
  "error": {
    "code": "INVALID_LINKEDIN_URL",
    "message": "Please provide a valid LinkedIn profile URL.",
    "request_id": "req_01..."
  }
}

Status	Meaning
`400`	Missing or invalid parameters
`401`	Missing, invalid, revoked, or expired API key
`403`	API key does not have access
`404`	Requested resource was not found
`429`	Rate or credit limit was exceeded
`500`	Unexpected internal error
`502`	Upstream provider error
`512`	`TEMPORARY_FETCH_FAILURE`; retry the request
`513`	`SOURCE_NOT_FOUND`; the source was deleted or moved, so do not retry repeatedly

Every response includes X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Include the request ID when contacting support.

Getting started

The seven APIs

Search APIs

MCP and results

Governance

Manage

Base URL and authentication

Endpoints

Look up an email

Validate an email

Get a profile

Get a company

Get profile posts

Get company posts

Cache strategies

Responses

​Base URL and authentication

​Endpoints

​Find an email from a social URL

​Look up an email

​Validate an email

​Get a profile

​Get a company

​Get profile posts

​Get company posts

​Cache strategies

​Responses

Base URL and authentication

Endpoints

Find an email from a social URL

Look up an email

Validate an email

Get a profile

Get a company

Get profile posts

Get company posts

Cache strategies

Responses