Data Conventions

This page describes how results represent LinkedIn data: which URLs you get back, how LinkedIn URNs identify people and content, how your account relates to them, how times are expressed, and what a missing value looks like.

URL normalization

Linked API normalizes all LinkedIn URLs in responses, regardless of the format provided in action parameters. Normalized URLs consistently follow these rules:

• Use https protocol.
• Include www subdomain.
• Exclude trailing slash (/).

For example, if action parameters include a URL like http://linkedin.com/in/person1/, the response will return it as https://www.linkedin.com/in/person1. Consider this behavior when implementing URL comparisons or storage in your integration.

LinkedIn URNs

Alongside URLs, action results expose LinkedIn's own internal identifiers in URN format. A URN is permanent: it does not change when a person edits their profile address or a company renames its page, which makes it a reliable key for storing and deduplicating records on your side.

Four types of URNs are returned:

• urn:li:member:123456789 – identifies a person.
• urn:li:organization:1234567 – identifies a company.
• urn:li:jobPosting:1234567890 – identifies a job posting.
• urn:li:activity:1234567890123456789 – identifies a post. A post URN can also be urn:li:share:<id> or urn:li:ugcPost:<id>, and the same post may be identified by more than one of them.

A URN identifies the same entity regardless of where it was found. The person returned by st.searchPeople and the same person returned by nv.openPersonPage carry an identical urn, so results of Standard and Sales Navigator actions can be matched against each other and against previously stored data.

The field is named urn when it identifies the entity the result is about, and receives a prefix when it points to a different entity. For example, companyUrn identifies the current company of a person and personUrn identifies the participant of a conversation.

Post URNs can also be sent back: every post action accepts postUrn in place of postUrl, so an identifier returned by one action can address the post in the next one without building a URL. See addressing a post by URN.

URNs are provided on a best-effort basis. LinkedIn does not expose an identifier on every page, and when an identifier is absent or ambiguous, the field is returned as null rather than guessed. Treat URNs as an enrichment of the existing URL fields, not as a replacement for them.

Viewer state

Results that describe a person or a piece of content also say how the account running the workflow relates to it, in a viewerState object. It is read from the same page as the rest of the result, so it adds no time to the action.

• On a person – search results, employees, decision makers, a person page, and the author of a post or comment:
  • connectionDegree – 1st, 2nd, or 3rd+, as LinkedIn shows it next to the name, or null when LinkedIn shows no degree, for example on your own content or on comments read in the feed or from LinkedIn's classic post layout.
• On a post or a comment:
  • reaction – your reaction (like, celebrate, support, love, insightful, funny), or null if you have not reacted or the page does not show it. Comments read in the feed or from LinkedIn's classic post layout always report null, so null alone does not prove you have not reacted.
  • isOwn – true if your account is the author, false if someone else is, or null if this cannot be told. Content published as a company page you administer counts as the company's, so it is false.

Timezone normalization

All date and time values returned by Linked API are in the UTC timezone. To display these values correctly in your integration, you should apply the appropriate offset for your user's local timezone.

Handling missing values

When certain data is unavailable on LinkedIn, some fields in action results may return as null or empty array ([]). Missing fields are always explicitly included in the response rather than being omitted.