In order to use the LittleSis API you must have an Api Token. You can get an Api Token from your LittleSis account settings page. If you don't yet have a LittleSis account, go here to create one. If you already have an account, access your settings page by either following this link or by clicking on your name in the navigation bar and going to 'settings'. On that page you will be able to generate an Api Token or view your current token.
Authorization is accomplished by including the http header Littlesis-Api-Token to each request.
Example:
curl -H 'Littlesis-Api-Token: RhS3mQneriAaym4pNjdjw' https://littlesis.org/api/entities/1
For brevity's sake, other examples in this document may omit the authorization header, but it is required for every request. The API will return status code 401 if you forget to include the Littlesis-Api-Token header and will return state code 403 if the token is invalid
The API follows many of the conventions of JSON API, but does not implement the entire specification.
All responses are in JSON.
For singular resources, this will return an object with two fields: data and meta. The meta object contains copyright, license, api version, and other similar information. The data object will have four fields: type, id, attributes, and links.
Type is the type of resource requested: (i.e. entities). Id is the resource's id. Attributes contain the resource attributes. Links contain at least one link to LittleSis where the resource can be viewed.
Structure of response:
{
data: {
type: 'resourceType'
id: '123'
attributes: { ... }
links: {
self: '/link/to/resource'
}
},
meta: { ... }
}
All successful responses will return status code 200
If an error occurs, the API will return json containing information about the error along with an error status code.
{
errors: [ {title: 'Details here about the error'} ],
meta: { ... }
}
| Status Code | Meaning |
|---|---|
| 400 | Missing required param |
| 401 | Missing Authorization Header |
| 403 | Invalid Authorization Header |
| 404 | Resource is missing or never existed |
| 410 | Resource has been deleted (but once existed) |
/api/entities/:idThis provides basic information about an entity:
To include additional information that's contained within the extensions, set the url query parameter details=TRUE
example:
curl https://littlesis.org/api/entities/1?details=TRUE However, this may not have useful information for every entity as some extensions do have additional fields.
/api/entities/:id/extensionsExtensions are also known as types. All entities have at least one type -- Organization or Person. Other types include: Business Person, Public Company, Political Candidate, and Professional Associations.
Example request: curl https://littlesis.org/api/entities/1/extensions
{
"data": [
{
"type": "extension-records",
"id": 1,
"attributes": {
"id": 1,
"definition_id": 2,
"display_name": "Organization",
"name": "Org"
}
},
{
"type": "extension-records",
"id": 2,
"attributes": {
"id": 2,
"definition_id": 5,
"display_name": "Business",
"name": "Business"
}
},
{
"type": "extension-records",
"id": 3,
"attributes": {
"id": 3,
"definition_id": 13,
"display_name": "Public Company",
"name": "PublicCompany"
}
}
],
"meta": {...}
}
/api/entities/:id/relationshipsRelationships this entity has with other entities. The key "data" contains an array of Relationship elements. These requests can also be paginated.
You can find limit the relationships to specific category by including the param "category_id".
/api/entities/:id/listsThe lists that the entity is on
Example request: curl https://littlesis.org/api/entities/10/lists
{
"meta": {
"copyright": "LittleSis CC BY-SA 3.0",
"license": "https://creativecommons.org/licenses/by-sa/3.0/us/",
"apiVersion": "2.0-beta"
},
"data": [
{
"type": "lists",
"id": 1,
"attributes": {
"id": 1,
"name": "Fortune 1000 Companies (2008)",
"description": "Fortune Magazine's list of the 1000 US companies with the largest published revenue figures.",
"is_ranked": true,
"is_featured": false,
"updated_at": "2017-02-01T15:46:35Z",
"short_description": null,
"entity_count": 1000
},
"links": {
"self": "https://littlesis.org/lists/1-fortune-1000-companies-2008"
}
},
{
"type": "lists",
"id": 291,
"attributes": {
"id": 291,
"name": "Top Lobbying Clients in New York State in 2011",
"description": "\"In 2011, 2,776 unique groups spent money lobbying in New York. The chart found from pages 2 through 97 of this report ranks each of them and compares their spending to 2010 levels.\"\r\n\r\n-NYPIRG, April 5, 2012",
"is_ranked": true,
"is_featured": false,
"updated_at": "2017-04-27T01:33:39Z",
"short_description": null,
"entity_count": 96
},
"links": {
"self": "https://littlesis.org/lists/291-top-lobbying-clients-in-new-york-state-in-2011"
}
}
]
}
/api/entities/search?q=NAMEExample response:
{
"data": [
{
// entity objects are identical to those returned by the /api/entities/:id route
},
],
"meta": {
"currentPage": 1,
"pageCount": 3,
"copyright": "LittleSis CC BY-SA 3.0",
"license": "https://creativecommons.org/licenses/by-sa/3.0/us/",
"apiVersion": "2.0-beta"
}
}
It will return at most 10 entities at a time. If there are more than 10 results, you can request additional pages by including the param page (page=NUMBER) to the request. Leaving out the param page is the same as requesting page 1
/api/relationships/:idThis provides basic information about a relationship:
The response object also includes information on the two entities in the relationship under the key 'included'
Example request: curl https://littlesis.org/api/relationships/297069
{
"meta": {
"copyright": "LittleSis CC BY-SA 3.0",
"license": "https://creativecommons.org/licenses/by-sa/3.0/us/",
"apiVersion": "2.0-beta"
},
"data": {
"type": "relationships",
"id": 297069,
"attributes": {
"id": 297069,
"entity1_id": 72489,
"entity2_id": 28778,
"category_id": 5,
"description1": "Campaign Contribution",
"description2": "Campaign Contribution",
"amount": 631700,
"goods": null,
"filings": 16,
"updated_at": "2017-07-25T18:18:13Z",
"start_date": "2004-00-00",
"end_date": "2016-04-25",
"is_current": null,
"description": "Robert Mercer gave money to Republican National Committee"
},
"links": {
"self": "https://littlesis.org/relationships/297069"
}
},
"included": [
{
"type": "entities",
"id": 72489,
"attributes": {
"id": 72489,
"name": "Robert Mercer",
"blurb": "Renaissance Tech billionaire, Club for Growth backer",
"summary": "Robert Mercer, 65, is co-CEO of Renaissance Technologies LLC, a $15 billion hedge fund. The IBM language-recognition whiz-turned-financier brought home $125 million in 2011, making him the 16th highest-earning hedge fund manager, according to Forbes.\r\n\r\nRenaissance Technologies is based in New York City, with additional locations in London and East Setauket, N.Y., where Mercer lives.",
"website": null,
"parent_id": null,
"primary_ext": "Person",
"updated_at": "2017-09-11T21:48:02Z",
"start_date": null,
"end_date": null,
"aliases": [
"Robert Mercer"
],
"types": [
"Person",
"Business Person"
]
},
"links": {
"self": "https://littlesis.org/entities/72489-Robert_Mercer"
}
},
{
"type": "entities",
"id": 28778,
"attributes": {
"id": 28778,
"name": "Republican National Committee",
"blurb": "The Grand Ol' Party",
"summary": null,
"website": null,
"parent_id": null,
"primary_ext": "Org",
"updated_at": "2017-10-09T01:09:46Z",
"start_date": null,
"end_date": null,
"aliases": [
"Republican National Committee",
"RNC"
],
"types": [
"Organization",
"Political Fundraising Committee",
"Other Campaign Committee"
]
},
"links": {
"self": "https://littlesis.org/entities/28778-Republican_National_Committee"
}
}
]
}