This API is currently available as a closed BETA. We invite interested parties to give us feedback on this API, its documentation, or anything else about Tumelo's transparency service prior to the API becoming generally available.

A changelog for the api can be found here.

The API is available at the following URL:

https://api.prod.tumelo.com/v1

For information on how to obtain access to the API, please contact us.

Development and Production environments are separated into their own habitats. Please contact us when you're ready to go into production and require access to your company's live habitat.

URLs, headers, path parameters, query parameter names, and query parameter values are all case sensitive. Be careful to use the correct case when constructing requests.

Requests may return an error indicating that there was a problem responding. The response will contain an HTTP status code as well as a JSON object in the following format which describes the error in more detail:

{
  "message": "Resource not found"
}

Requests that return lists and describe pagination parameters support paginated results. Results are separated into multiple pages, where the size of each page is determined by the pageSize query parameter. If omitted, pageSize defaults to 50 records. When a response includes a nextPageToken in the response body, this token value should be passed as a query parameter nextPageToken to the same endpoint in order to retrieve the next page of results. This process should be repeated until the response doesn’t include a nextPageToken, indicating that the end of the results has been reached.

When passing the nextPageToken parameter, all other filter and query parameters present in the previous request, must be filled. Filter parameters must not be changed while paginating since this will result in an error or an incorrect overall list. The nextPageToken will not be present in the response body if the end of the list has been reached and no further results are available.

The following string formats are used throughout this API.

date-time

The valid format is date-time notation as defined by RFC 3339, section 5.6.

For example: 2020-11-30T10:45:28Z

If you have any technical questions relating to the Tumelo API, please contact us, explaining your question or issue in as much detail as possible, including the operation you were performing and the ISIN or Organization ID you were querying, as well as the results you expected and the actual results or error message you observed. You can expect a response within one business day.

During development and testing in your development habitat we make available a test data set that includes some sample data constructed to illustrate functionality. It is not intended to be used for any purpose other than testing and/or demonstrating functionality, and should not be relied upon to be an accurate reflection of the underlying holdings of any real fund.

If you have any questions or concerns about the data accuracy or completeness of the data in the production environment, please report the matter to us, giving as much information as possible about the issue.

An instrument may have a composition, this means it is a fund invested in other instruments.

A breakdown is the bottom level components of a composite instrument or account. By this, we mean organizations and cash that a particular composite instrument or account is invested into either directly or through funds.

Breakdowns also have an other listing, this is for funds that only have partial information available, or where an instrument is not mapped to an organization.

All requests to the Tumelo API must be authenticated using an access token. You will be given a username, password and habitatId to access the API. To obtain an access token, call the authenticate endpoint and provide these details. A token will be returned which can be used to access the API for a particular amount of time. When the access token expires you will need to call the endpoint again to acquire a new token.

If you wish to change your password for security purposes you can use the changePassword endpoint to do so.

Advanced Usage

Amazon's AWS Cognito Identity Provider Service is the identity provider responsible for issuing the token(s). If you wish you can communicate with AWS Cognito directly. You obtain API access tokens by authenticating with Cognito using the credentials issued to your company by Tumelo. You then use the IdToken issued by Cognito in each subsequent request to the Tumelo API.

This process of authenticating directly with cognito is described in detail in the Authentication Developer Guide.

Instruments are financial assets that can be traded on the world's financial markets. The classes of asset that we are most concerned with for the purposes of investor transparency include stocks and shares, bonds, cash and tradeable funds of any kind. These are typically the types of asset used by fund managers to make up pensions and other investment products that retail investors and employees invest in, either directly or via a pension scheme.

The Tumelo Transparency API makes it easy to discover the underlying instruments making up a fund. We distinguish two main classes of instrument, depending on whether the instrument represents a simple share in a company or it represents a fund such as an ETF that is made up of many underlying instruments. We refer to instruments that can't be broken down or decomposed into constituent instruments as atomic, and those that can be decomposed as composite.

All instruments on the Tumelo platform are identified by their ISIN (International Securities Identification Number).

Organizations represent public companies and other institutions such as governments that issue shares or bonds which are then traded on the world's financial markets.

In order to be able to unambiguously refer to a specific company or other organization, we make use of Organization Identifiers. Any given organization will have at least one identifier associated with it. The majority of organizations have an associated Legal Entity Identifier (LEI), which is a 20-character alpha-numeric code based on the ISO 17442 standard. LEIs are managed by the Global Legal Entity Identifier Foundation (GLEIF) which describes itself as a supra-national not-for-profit organization headquartered in Switzerland.

LEI is a relatively new standard, but companies involved in settling trades within the EU are required by regulation to have an LEI. Some organizations, particularly those outside the EU may not have an LEI yet, so we also support other identification schemes. Currently this includes D-U-N-S numbers, issued by Dunn & Bradstreet.

When using the Transparency API, organization identifiers are prefixed by the name of the identification scheme, separated from the identifier itself by an underscore _ character, for example LEI_HWUPKR0MPOU8FGXBT394 or DUNS_152618153.

Whilst most organizations will have a single associated identifier, it is possible for an organization to have more than one identifier. When the information relating to a specific organization returned, all known identifiers are included.

Habitats represent a private view or slice of the Tumelo platform as seen by a service user. A habitat provides an environment to manage distinct sets of investors with varying accout configurations. Typically, a customer will be assigned two distinct habitats:

• Test
• Production

The unique identifier for each habitat will be communicated to the user as part of the onboarding process.

Each habitat has a set of subscribed instruments. Only subscribed instruments can:

• be added to the account of an investor
• have have an organization breakdown computed

You can see the full list of instruments to which your habitat is subscribed using the Get Subscribed Instruments endpoint (/habitats/{habitatId}/instruments).

Adding or removing subscribed instruments

If you wish to add or remove instruments from your subscribed instrument set please email support@tumelo.com.

Investors hold investments in financial assets. Each investor can have a number of accounts providing access to a variety of investment portfolios.

Investors are associated with a habitat and each habitat has its own distinct set of investors.

All investor operations must be performed within your assigned habitat, otherwise a response of 403 Forbidden is returned.

The account is the entity that holds the investor's investment funds. An investor may hold multiple accounts to support the separation of investment choices, such as ISAs or pensions.

The configuration of an account is represented by a composition entity which describes the account's components in terms of weighted investment instruments, cash and others.

The modelPortfolio is an entity that can hold compositions defined by the API user. Its intended uses are:

• computing breakdowns for user defined portfolios
• assigning to a user account where it can represent an investment portfolio that is shared by multiple investors

Polls represent an opportunity for an investor to respond to a specific question, referred to here as a proposal (also known as a resolution), being asked at an organization's shareholder meeting, typically an AGM (Annual General Meeting) or EGM (Extraordinary General Meeting).

A poll will close before (generally two weeks) the shareholder meeting so there is time to communicate the results of the poll to the fund manager before the shareholder meeting occurs.