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.
Access and Authentication
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
API Reference
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”
},
…
]
}
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”
}
…
]
}
…
]
}
…
]
}
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”: “Company Name”,
“notes”: [
{
“actor”: “Test Firm Owner”,
“note”: “Test note”,
“date”: “2020-06-16”
}
…
]
}
…
]
}
Returns an array of objects containing investment summary.
API call
/api/investor/:investor_id/portfolio_summary_table/?token=YOUR-GENERATED_TOKEN
Parameters:
fund_id (required): Fund id to scope all investments by fund.
investment_id: Investment id to scope by single investment.
Response Sample
{
“data”: [
{
“investment_name”: “Company Name”,
“investment_id”: 595,
“Current PM Valuation”: 997.82,
“Total Ownership”: 0.6923,
“Total Invested”: 28119.55,
“Total Realized”: 0.0,
“Current Value of Investment”: 693.94,
“Number of Shares”: 4500.0,
“Current Book Value”: 0.0,
“Investment Multiple”: 0.024678204309812928,
“Date of 1st Investment”: “2021-06-01”,
“Stage”: “Series A”,
“Type”: “Marketplace,B2C”,
“Industry”: “Information Technology”,
“Location”: “United States, Cupertino”,
“Status”: “gray”,
“Fundraising”: “green”
}
…
]
}
Returns an array of array where each array contains investment transactions.
API call
/api/investor/:investor_id/portfolio_summary_table/?token=YOUR-GENERATED_TOKEN
Parameters:
fund_id: Fund id to scope all investments by fund.
investment_id: Investment id to scope by single investment.
Response Sample
{
“data”: [
[
{
“investment_name”: “Company Name”,
“investment_id”: 595,
“Source”: “custom”,
“Date”: “2021-06-01”,
“Transaction Type”: “Equity issue”,
“Share Class/Convertible”: “Common”,
“Share Class/Convertible source”: “custom”,
“Assigned-to”: null,
“Comments”: null,
“Currency”: “USD”,
“Spot rate to”: 1.1024,
“FD # Shares”: 3500.0,
“# Shares”: 3000.0,
“# Options”: 500.0,
“Convertible Principal”: “”,
“FD % Ownership”: 0.5385,
“Current Value of Investment”: 595.0,
“Invested”: null,
“Realized”: null,
“Invested Currency”: null,
“Closing Date”: “2021-06-01”,
“Raised”: 0.0,
“Pre-Money”: 0.0,
“Post-Money”: 0.0,
“# Shares (total)”: 3000.0,
“# Options (total)”: 500.0,
“Conv. Eqv. Options (total)”: 0.0,
“# Shares (new)”: 3000.0,
“# Options (new)”: 500.0,
“Conv. Eqv. Options (new)”: 0.0,
“Share Price”: 0.0,
“FD Share price”: 0.0,
“Preferred Share Type”: false,
“Voting Rights”: false,
“Dividends”: false,
“Liquidation Preference Type”: “none”,
“Multiplier”: null,
“Seniority”: null,
“Participating”: false,
“Issue Date”: “”,
“Principal”: “”,
“Valuation”: “”,
“Discount”: “”,
“Interest Rate”: “”,
“Interest Accrual”: “”,
“Maturity Date”: “”,
“Qualified Financing Amount”: “”
},
…
]
…
]
}
End-to-end Example
This video shows the API working as part of a Google Docs script.