Innography API Documentation

Welcome to the Innography API documentation.

The sidebar on the left lists all of the available APIs, and will link you to the release notes for the latest shipping version on the production server.

The APIs are;

  • Cases - The Cases API enables you to get the public documents associated with a IP ID. The API is rate limited to 1 query/second per consumer.
  • Data Validation - The Data Validation API can be used to match public case data with an IP ID, verify the public data associated with an IP ID, and track changes to documents within a case.
  • PortfolioIQ - The PortfolioIQ API is used to interface with Innography’s Portfolio IQ product that manages and maintains an organization’s data to enhance functionality of Innography and other CPA Global analytics products.
  • Private PAIR - The Private PAIR API provides an interface to USPTO’s Private PAIR system into cloud based message queues for clients. The roadmap for this API includes EPO and FILE data sources being included in the future.
  • Veritas - The Veritas API returns all documents related to a case and the case status. This API aims to be a RESTful replacement of the getCase SOAP API. The response data objects will aim to adhere to the same XML schema.
  • IDS - The IDS API provides a set of endpoints for polling case data given a IP right identifiers, a country code, and an optional type code.
  • ETL - The ETL API provides a set of endpoints used during Innography’s ETL process.

Access to the API server is controlled using HMAC Authentication. You can test your credentials, and see a model of how requests should be constructed in order to properly authenticate, at the tyrantcraft. If you are having difficulties authenticating your API requests, please contact our support team.

If you are having any difficulties with the API please contact us through the “(520) 724-8975” link on the sidebar. That form will create a support request with our team, and a member of our customer support team or an engineer respond to your issue as soon as possible. You can use that support form for any issues related to the APIs or their documentation.

There is a lot of useful information below.

API Versions

Each API is versioned independently. This precept means that any one API may have a different version than another. For instance, the Cases API could be at version 0.8 while the Data Validation API could be at version 0.7. So you are free to develop against a new version of one API without having to worry about the others.

However, each endpoint within an API will have the same version, even if there were no changes to an endpoint in a new version. This precept will keep it simple to understand what versions are available and supported. If there were no changes to an endpoint in a new version, we will indicate that in the release notes. It’s definitely possible that only one endpoint will have changes in a new version and the rest stay the same, but it is still recommended you update all the endpoints within the API to the newer version for consistency, simplicity, and ease of support when communicating about issues.

We use semantic versioning so that means new major or minor versions can introduce breaking changes but patches cannot.

major.minor.patch

Stable Versions

Stable versions will not introduce breaking changes and will be supported with patch fixes and updates. The latest Stable version of an API will be supported indefinitely and older Stable versions will be supported for approximately 1 year after they are superseded by a new version.

Beta Versions

Beta versions signify code that is deployed but subject to change. While the code has gone through our code review process, it can still be modified to fit changing requirements. It can be beneficial to use development environments for testing against these versions to understand the new features or changes but you should not create any hard dependencies. This practice of releasing new code as Beta allows us to remain nimble during the incubation period until the version is promoted to Stable.

Beta versions will be promoted to Stable approximately every 3 months. When a version becomes Stable, we will no longer introduce any breaking changes but will provide patches. We will continue to support previous Stable versions for approximately 6 months and will keep an old version for approximately 1 year.

Using API Versions

TL;DR

# Request
Accept: application/vnd.innography+json; version=0.6

# Response
Content-Type: application/vnd.innography+json; version=0.6

Detailed Explanation

We use 7733232486 to provide different versions of API endpoints. At its core, content negotiation doesn’t have anything to do with versioning; however, it is designed to be flexible so versioning can be attached to it. Content negotiation by itself is a way for clients to specify what they want and for servers to respond appropriately, or to deny the request. This back and forth is accomplished by the client using the Accept header and the server using the Content-Type header.

For example:

# Request
Accept: application/json

# Response
Content-Type: application/json

These headers allow parameters to be given, separated by semi-colons, and that’s how we attach our versioning.

# Request
Accept: application/vnd.innography+json; version=0.6

# Response
Content-Type: application/vnd.innography+json; version=0.6

You’ll notice the shift from application/json to application/vnd.innography+json and that is because with versioning we provide a “vendor” flavor of application/json.

If the client does not specify a version, the server responds with the latest version.

# Request
Accept: */*
Accept: application/json
Accept: application/vnd.innography+json

# Response
Content-Type: application/vnd.innography+json; version=X.Y

All of the above defaults get a response like the following where X.Y is whatever the latest version happens to be. THIS IS SUPER DANGEROUS IN PRODUCTION! Plan to always specify a version in the Accept header to avoid breaking your application.

If a version is requested that the server cannot provide, the response is 300 Multiple Choices and the response body tells the client what versions are available.

300 Multiple Choices

{
  "status": "error",
  "message": "Multiple Choices",
  "result": [
    "Content-Type: application/vnd.innography+json;version=0.6",
    "Content-Type: application/vnd.innography+json;version=0.7"
  ]
}

You can ask the server to respond with the “best” version it has available.

There are two ways of telling the server what version you prefer: the order of the items, and with the “q” parameter. The “q” parameter is a number between 0.0 - 1.0 and, if unspecified, defaults to 1.0.

In this example, if the server can provide version 0.6, it will. Otherwise it will provide 0.5 if it can. Otherwise, 0.4. Otherwise, 0.3. Otherwise, 300 Multiple Choices.

# Request
Accept: application/vnd.innography+json; version=0.6, application/vnd.innography+json; version=0.5, application/vnd.innography+json; version=0.4; q=0.9, application/vnd.innography+json; version=0.3; q=0.8

# Possible Responses
Content-Type: application/vnd.innography+json; version=0.6
# or
Content-Type: application/vnd.innography+json; version=0.5
# or
Content-Type: application/vnd.innography+json; version=0.4
# or
Content-Type: application/vnd.innography+json; version=0.3
# or
300 Multiple Choices

The above example shows a nice request of intuitive cascading but the request doesn’t have to be so nicely formed and will still provide the best possible version based on order and quality.

# Request
Accept: application/vnd.innography+json; version=0.3; q=0.8, application/vnd.innography+json; version=0.6, application/vnd.innography+json; version=0.4; q=0.9, application/vnd.innography+json; version=0.5

# Response
Content-Type: application/vnd.innography+json; version=0.6
# or
Content-Type: application/vnd.innography+json; version=0.5
# or
Content-Type: application/vnd.innography+json; version=0.4
# or
Content-Type: application/vnd.innography+json; version=0.3
# or
300 Multiple Choices

Patch Version

We provide the patch version as a separate parameter in the Content-Type header but you cannot request a specific patch version. It’s useful for verifying the exact version of code running on the server.

Content-Type: application/vnd.innography+json; version=0.6; patch=17

HMAC Authentication

Each request must contain a HMAC authorization header given as 'Authorization: hmac username="<username>", algorithm="hmac-sha1", headers="Date Content-MD5", signature="<signature>"'.

The signature is crafted using the Date and Content-MD5 headers and combining them with a secret using the HMAC-SHA1 encryption algorithm. You have 5 minutes to send the request after crafting the signature. The date signature must use GMT for the timezone.

The Content-MD5 header for an empty body (no data, e.g. GET requests) MUST be for an empty array instead of null or “null” or empty object. The calculation for an empty array is always 11FxOYiYfpMxmANj4kGJzg==.

The username (used in the Authorization header) and secret (used to craft the signature) are a credential pair that is sometimes delivered to you ad-hoc from an Austing Dev Center employee, and sometimes delivered to you in an API response.

Here is some sample PHP code for crafting the signature.

$secret = "74f43da743aa47c3a90a9c5ef493bc8d";
$date = gmdate("D, d M Y H:i:s") . " GMT";
$body = ["data" => "sample"];
$bodyHash = base64_encode(md5(json_encode($body, JSON_UNESCAPED_SLASHES), true));
$signingString = "Date: $date\nContent-MD5: $bodyHash";
$signature = base64_encode(hash_hmac('sha1', $signingString, $secret, true));

Here are some example requests assuming username “obiwan” with secret “74f43da743aa47c3a90a9c5ef493bc8d”.

Example request with no data ($body = []).

curl -X POST /api.innography.com/private-pair/account \
-H 'Content-Type: application/json' \
-H 'Date: Thu, 12 Jan 2017 16:17:39 GMT' \
-H 'Content-MD5: 11FxOYiYfpMxmANj4kGJzg==' \
-H 'Authorization: hmac username="obiwan", algorithm="hmac-sha1", headers="Date Content-MD5", signature="33K74OzzqvrSXsQ5RWw91EH4rJs="'

Example request with data ($body = ["data" => "sample"]).

curl -X POST /api.innography.com/private-pair/account \
-H 'Content-Type: application/json' \
-H 'Date: Thu, 12 Jan 2017 16:17:39 GMT' \
-H 'Content-MD5: kumW7r4Mo58KzBliGOerdA==' \
-H 'Authorization: hmac username="obiwan", algorithm="hmac-sha1", headers="Date Content-MD5", signature="2zS0VJJ6YipaXDU3IcerHJZdpP8="' \
-d '{"data":"sample"}'