LittleSis Api Documentation - Version 2

This is the documentation for version 2 of the API, which is in active development and SUBJECT TO CHANGE.

Signup and Authorization

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.


curl -H 'Littlesis-Api-Token: RhS3mQneriAaym4pNjdjw'

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.

Successful Responses

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.

Structure of an error response:

  errors: [ {title: 'Details here about the error'} ],
  meta: { ... }

Error Status Codes

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)

Entity Resources


This provides basic information about an entity:

  • name: The primary alias (not necessarily unique) of the Entity in LittleSis
  • blurb: A short phrase or sentence describing the Entity
  • primary_ext: "Person" or "Org"
  • summary: A longer bio or summary of the Entity
  • website: The Entity's website
  • start_date: The date when the Entity came to exist -- DOB for people, founding dates for orgs
  • end_date: The date, if any, when the Entity ceased to exist
  • parent_id: If the Entity is a sub-organization of a parent Entity, the parent's id is stored here
  • updated_at: The last time the Entity data was updated
  • types: An array of types (also known as extensions) associated with the entity. i.e. Business, Lawyer
  • aliases: An array of other names the entity is known as

To include additional information that's contained within the extensions, set the url query parameter details=TRUE



However, this may not have useful information for every entity as some extensions do have additional fields.

Entity Extension


Extensions 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

  "data": [
      "type": "extension-records",
      "id": 1,
      "attributes": {
        "definition_id": 2,
        "display_name": "Organization",
        "name": "Org"
      "type": "extension-records",
      "id": 2,
      "attributes": {
        "definition_id": 5,
        "display_name": "Business",
        "name": "Business"
      "type": "extension-records",
      "id": 3,
      "attributes": {
        "definition_id": 13,
        "display_name": "Public Company",
        "name": "PublicCompany"
  "meta": {...}

Search by name


This searches our database for entities. The number of the relationships the entity has is used in the ranking algorithm. For instance, searching for 'Bush' will put George Bush before Jeb Bush because the former has more relationships in our database than the latter.

Example 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": "",
	"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