API Requests with JSON

We support two formats for API requests and responses: XML and JSON. Our schema was originally designed to take advantage of XML features not available in JSON, such as attributes, or difficult to use in languages that often use JSON, such as hyphenated element names.

To make our JSON format easy to use despite this, we modified our schema for JSON requests. So, when you see XML output in our documentation, you will need to translate it in your mind to the appropriate schema when using JSON. Our hope is that this will be relatively straight-forward by inspecting the results.

But to make sure things are 100% clear, the documentation takes a sample result, showing it in XML and JSON, and walks through the differences.

Indicating you want to use JSON or JSONP

You can  retrieve JSON data using the new "format" parameter:

You can also tell us you want JSON by sending a HTTP header of x-li-format with a value of json.

x-li-format: json

Now you receive JSON-formatted data from API calls instead of the default format of XML.

To get JSONP, send the same HTTP header, but use a value of jsonp instead:

x-li-format: jsonp

When using JSONP, pass a callback query parameter to specify the name of the JavaScript function you want us to pass the results to; otherwise, we use the default function name of callback().

Optionally specify an error-callback query parameter, which we call whenever we would return a response code of 4xx or 5xx. In these cases, we will instead return 200 and pass the error body as JSON to the error callback.

For example:

Gives:

firstNameResponse({"id": "uxf0AC9ZM-"})

To let you identify response format programmatically, we provide an x-li-format HTTP header of our own. This comes back on all requests, with a value of either xml, json, or jsonp. This gives you a way to easily validate your format request was properly received and lets you know the format without needing to try and parse the data.

For those into the HTTP spec, we also set a Vary header of x-li-format to let you know we returned a different representation of the request. This is useful for caches and proxies.

If you are writing data using PUT or POST, you will need to either send a HTTP header of x-li-format with a value of json, or set Content-Type to application/json

x-li-format: json
or
Content-type: application/json

Reading JSON data

Here's an example of XML output compared to JSON, using a request for two profiles:

This request returns a people element with an attribute named total and two nested person elements. Each person element has an attribute of key and two children elements: first-name and connections.

The first-name element contains text, such as Adam. The connections element is empty, but has a total attribute, similar to people.

XML

JSON

<people total="2">
  <person key="~">
	<first-name>Adam</first-name>
	<connections total="129" />
  </person>
  <person key="hks0NPUMZF">
	<first-name>Brandon</first-name>
	<connections total="500" />
  </person>
</people>

{
  "values": [
	{
	  "_key": "~",
	  "connections": {"_total": 129},
	  "firstName": "Adam"
	},
	{
	  "_key": "hks0NPUMZF",
	  "connections": {"_total": 500},
	  "firstName": "Brandon"
	}
  ],
  "_total": 2
}

Looking at the two versions, there are six differences:

  1. XML uses hyphen-ated field names. JSON uses camelCase field names.

  2. XML nodes containing strings and numbers are become JSON strings and numbers.

  3. XML nodes containing children elements of different names become JSON hashes.

  4. XML attributes are renamed to have a leading underscore and placed inside the original node.

  5. XML nodes containing children elements of the same name become array elements inside an element named values.

  6. The XML root node disappears.

Let's walk through them one at a time.

1. XML uses hyphen-ated field names. JSON uses camelCase field names.

When field name contains a hyphen, it's removed and the next character is upper cased. In this example, first-name is now firstName.

Our REST request URLs stay the same regardless whether you're using XML or JSON. Do not ask for https://api.linkedin.com/v1/people/~:(firstName).

XML

JSON

<people total="2">
  <person key="~">
	<first-name>Adam</first-name>
	<connections total="129" />
  </person>
  <person key="hks0NPUMZF">
	<first-name>Brandon</first-name>
	<connections total="500" />
  </person>
</people>

{
  "values": [
	{
	  "_key": "~",
	  "connections": {"_total": 129},
	  "firstName": "Adam"
	},
	{
	  "_key": "hks0NPUMZF",
	  "connections": {"_total": 500},
	  "firstName": "Brandon"
	}
  ],
  "_total": 2
}

2. XML nodes containing strings and numbers are become JSON strings and numbers

When an XML element contains only text, it stays as text. When it contains a number, we keep it as a number. So, Adam is still Adam.

XML

JSON

<people total="2">
  <person key="~">
	<first-name>Adam</first-name>
	<connections total="129" />
  </person>
  <person key="hks0NPUMZF">
	<first-name>Brandon</first-name>
	<connections total="500" />
  </person>
</people>

{
  "values": [
	{
	  "_key": "~",
	  "connections": {"_total": 129},
	  "firstName": "Adam"
	},
	{
	  "_key": "hks0NPUMZF",
	  "connections": {"_total": 500},
	  "firstName": "Brandon"
	}
  ],
  "_total": 2
}

3. XML nodes containing children elements of different names become JSON hashes.

Here, the person element contains first-name and connections. These become two of the three elements of the hash. Since JSON hashes are unordered, the fields may or may not appear in the same sequence in JSON output as XML output.

XML

JSON

<people total="2">
  <person key="~">
	<first-name>Adam</first-name>
	<connections total="129" />
  </person>
  <person key="hks0NPUMZF">
	<first-name>Brandon</first-name>
	<connections total="500" />
  </person>
</people>

{
  "values": [
	{
	  "_key": "~",
	  "connections": {"_total": 129},
	  "firstName": "Adam"
	},
	{
	  "_key": "hks0NPUMZF",
	  "connections": {"_total": 500},
	  "firstName": "Brandon"
	}
  ],
  "_total": 2
}

4. XML attributes are renamed to have a leading underscore and placed inside the original node.

Since JSON lacks a notion of attributes, they are converted to hash keys and placed inside the element. To avoid name conflicts, we prepend an underscore to the name.

Here, key becomes _key and  total becomes _total.

The total attribute actually appears inside of both  people and inside of connections. In this example, connections is empty; it doesn't contain any connection elements. However, we still add the attribute.

XML

JSON

<people total="2">
  <person key="~">
	<first-name>Adam</first-name>
	<connections total="129" />
  </person>
  <person key="hks0NPUMZF">
	<first-name>Brandon</first-name>
	<connections total="500" />
  </person>
</people>

{
  "values": [
	{
	  "_key": "~",
	  "connections": {"_total": 129},
	  "firstName": "Adam"
	},
	{
	  "_key": "hks0NPUMZF",
	  "connections": {"_total": 500},
	  "firstName": "Brandon"
	}
  ],
  "_total": 2
}

In the event an XML node containing only text or a number has an attribute, we will omit that data from the reply. This is to drastically simplify the commmon case. We don't conditionally modify the response because that would also add additional complexity.

5. XML nodes containing children elements of the same name become array elements inside an element named values.

When a node contains a collection of similarly named sub-nodes, the sub-nodes become array elements inside a values key. Here, the people node has two person sub-nodes.

XML

JSON

<people total="2">
  <person key="~">
	<first-name>Adam</first-name>
	<connections total="129" />
  </person>
  <person key="hks0NPUMZF">
	<first-name>Brandon</first-name>
	<connections total="500" />
  </person>
</people>

{
  "values": [
	{
	  "_key": "~",
	  "connections": {"_total": 129},
	  "firstName": "Adam"
	},
	{
	  "_key": "hks0NPUMZF",
	  "connections": {"_total": 500},
	  "firstName": "Brandon"
	}
  ],
  "_total": 2
}

6. The XML root node disappears.

There is no concept of a root element in JSON. So, the XML root element, in this case people, is removed.

XML

JSON

<people total="2">
  <person key="~">
	<first-name>Adam</first-name>
	<connections total="129" />
  </person>
  <person key="hks0NPUMZF">
	<first-name>Brandon</first-name>
	<connections total="500" />
  </person>
</people>

{
  "values": [
	{
	  "_key": "~",
	  "connections": {"_total": 129},
	  "firstName": "Adam"
	},
	{
	  "_key": "hks0NPUMZF",
	  "connections": {"_total": 500},
	  "firstName": "Brandon"
	}
  ],
  "_total": 2
}

Sending JSON data

Regardless of your output format, you can choose whether to send us XML or JSON in a HTTP POST/PUT body. You will need to set Content-Type to application/json on your JSON posts as well as setting the "x-li-format" header to "json".

Here is what you could POST for a reshare:

XML

JSON

<share>
  <attribution>
	<share>
	  <id>s148028014</id>
	</share>
  </attribution>
  <visibility>
	<code>anyone</code>
  </visibility>
</share>
{
  "attribution": {
	"share": {
		"id": "s148028014"
	}
  },
  "visibility": {
	"code": "anyone"
  }
}

A POST for a status update:

XML

JSON

<activity locale="en_US">
    <content-type>
        linkedin-html
    </content-type>
   <body>
        My Fancy Update
    </body>
</activity>
{
	"contentType":"linkedin-html",
	"body":"My Fancy Update"
}

Using PUT with JSON to add a "Like" to a share.  This one is tricky because stripping the top level leaves just the bare "true" or "false" - but this will work correctly.

XML

JSON

<is-liked>
   true
</is-liked>
true

Both formats are understood by our API server. However, when you POST or PUT JSON data, it needs to undergo the same set of schema changes to match what we send back using JSON.