Investor's API

Our Investor’s API allows you to access data from portfolio companies, and use it in a flexible way to build your own tailored reports, crunch it in your preferred analytic tool, or integrate it in your own website. This initial release allows you to access Basic Data about your investments (name, sector, website, etc.), KPIs, and Notes, and simple query parameters like investment (company) id or date for KPI/notes. Future releases will extend this to the whole portfolio data, including capt-table, fundraising, etc. Using the API requires some generic technical expertise (http querying, JSON parsing, etc.). If you don’t have it in-house, do contact us and we’ll be happy to help.

 

Base URL

The base URL for all the API endpoints is https://app.investory.io/api/investor/:id 

Authentication

The Investor API uses JSON Web Tokens (JWT) to authenticate all API requests. These tokens offer a method to establish secure server-to-server authentication by transferring a compact JSON object with a signed payload of your account’s secret key.

Accessing your secret key

You can find your secret key from the Account Settings page. There will be a secret key section in there where you’ll be able to find it.

There’s also a link to reset your secret key in case you think it was compromised.

Please, keep in mind to not share your secret key with anyone.

Creating a JWT

JSON Web Tokens are composed of three sections: a header, a payload (containing a claim set), and a signature. The header and payload are JSON objects, which are serialized to UTF-8 bytes, then encoded using base64url encoding.

The JWT’s header, payload, and signature are concatenated with periods (.). As a result, a JWT typically takes the following form: 

{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}

We recommend libraries provided on jwt.io. While other libraries can create JWT, these recommended libraries are the most robust. There is also a generator on their page which can be used to generate your token. 

Header

Property alg defines which signing algorithm is being used. Investor API uses HS256. Property type defines the type of token and it is always JWT.

{

“alg”: “HS256”,
“typ”: “JWT”

}

Payload

The second part of the token is the payload, which contains the claims or the pieces of information being passed about the user and any metadata required. You may find in the Api Reference section below the parameters you can include inside the payload to get more specific data.

*parameters names need to be included with quotation marks 

{

“investment_id”: 1,

“date_from”: “2020-01-01”,

“date_to”: “2020-02-01”

}

Signature

To create the signature part you have to take the encoded header, the encoded payload, the secret key, the algorithm specified in the header, and sign that. The signature is used to verify the message wasn’t changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is.

 HMACSHA256(

 base64UrlEncode(header) + “.” +

 base64UrlEncode(payload),

 YOUR-SECRET-KEY)

Putting all together

The output is three Base64-URL strings separated by dots. The following shows a JWT that has the previous header and payload encoded, and it is signed with a secret.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.YmcqBLDhsWkcNtVM-QCabqUWwX1ddYf4HBch0in1fZk

Base64 encoded header: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Base64 encoded payload: e30

Signature: YmcqBLDhsWkcNtVM-QCabqUWwX1ddYf4HBch0in1fZk

Portfolio Basic Data

Returns an array of objects containing basic data from all Investments.

API call

/api/investor/:investor_id/portfolio_basic_data/?token=YOUR-GENERATED_TOKEN

Parameters

investment_id:  Investment id to scope by single investment.

Response Sample:

{

 “data”: [

 {

 “investment_id”: 1,

 “investment_name”: “Company Name”,

 “business_model”: “Events”,

 “business_type”: “B2B”,

 “industry”: “Health Care”,

 “stage”: “pre seed”,

 “established”: “2020”,

 “location”: “France, Paris”

 },

 …

 ]

}

Portfolio KPIs

Returns an array of objects where each object has a “kpis” key which is another array of objects containing each KPI’s info. Inside you can find each KPI’s metric, type and values having the latter as another array of objects.

API call:

/api/investor/:investor_id/portfolio_kpis/?token=YOUR-GENERATED_TOKEN

Parameters: 

investment_id : Investment id to scope by single investment. The investment ids can be obtained by running the investment-data query above

metric_list:  If true, just provides the list of KPI metrics defined by a company, so you can iterate on. When set, the rest of parameters don’t apply.  

metric: Scope by KPI’s metric name.

date_from: If not informed, provides the latest available KPIs for each company. If informed, provide KPIs from the required date. Format is YYYY-MM-DD 

date_to: If not informed, provides the latest available KPIs for each company. If informed, provide KPIs to the required date. Format is YYYY-MM-DD

*All parameters can be combined with each other, except when “metric_list” is set.

Response Sample

{

 “data”: [

 {

 “investment_id”: 1,

 “investment_name”: “Company Name”,

 “kpis”: [

 {

  “metric”: “Revenue”,

 “type”: “monthly”,

 “values”: [

 {

 “actual”: 2500,

 “forecast”: 2000,

 “date”: “2016-01-01”,

 “creation_date”: “2016-09-06”,

 “update_date”: “2016-09-06”

 }

 …

 ]

 }

 …

 ]

 }

 …

 ]

 }

Portfolio Notes

Returns an array of objects where each object has a “notes” key which is another array of objects containing each note’s info. Inside you can find each note’s actor, date and the note itself.

API call

/api/investor/:investor_id/portfolio_notes/?token=YOUR-GENERATED_TOKEN

Parameters: 

investment_id :  Investment id to scope by single investment.

date_from: If not informed, provides all the available notes. If informed, provide notes from the required date. Format is YYYY-MM-DD

date_to: If not informed, provides all the available notes. If informed, provide notes to the required date. Format is YYYY-MM-DD

 *All parameters can be combined with each other.

Response Sample 

{

 “data”: [

 {

 “investment_id”: 650,

 “investment_name”: “Petronila 2000”,

 “notes”: [

 {

 “actor”: “Test Firm Owner”,

 “note”: “Test note”,

 “date”: “2020-06-16”

 }

 …

 ]

 }

 …

 ]

 }

End-to-end Example

This video shows the API working as part of a Google Docs script.

Investor API – google script.mp4

Get Your Free Sample Update

The options of updates on investory are limitless:

 - Individual formatting and limitless context sections

 - Fully customizable charts, funnels and tables

 - Add images and documents to your report

Check your e-Mail inbox for our sample reporting!