Guides

Listing firm investments

How to list all investments in an investment firm

---

How to list all investments in an investment firm?

With the release of the Investor - Securities API, it is now possible to programatically access and manipulate all investments in an investment firm.

Investments are grouped into 3 categories: certificates, warrants and convertible notes. To list all investments you must query these APIs and manipulate the results as you see fit.

Here's a quick step by step guide on how to do so:

1. Refer to the sample app guide for instructions on how to generate an access token. Make sure the CLIENT_ID and CLIENT_SECRET you use are associated with an OAuth application that contains the read_investor_securities scope, otherwise the generated access token won't have permission to access the "Investor - Securities" endpoints.

2. Once you posess the access token, here's an example Python code that would fetch all your investments:

import requests

INVESTMENT_FIRM_ID = "<REPLACE WITH YOUR INVESTMENT FIRM ID>"
ACCESS_TOKEN = "<REPLACE WITH ACCESS_TOKEN FROM STEP #1>"


def list_certificates(investment_firm_id: str) -> list[dict[str, Any]]:
    certificates = []

    response = requests.get(
        f"https://api.carta.com/v1alpha1/investors/firms/{investment_firm_id}/funds/-/investments/-/certificates",
        headers={
            "Bearer": ACCESS_TOKEN,
        },
    )
    content = response.json()
    certificates.extend(content["certificates"])
    next_page_token = content["nextPageToken"]

    while next_page_token:
        response = requests.get(
            f"https://api.carta.com/v1alpha1/investors/firms/{investment_firm_id}/funds/-/investments/-/certificates?pageToken={next_page_token}",
            headers={
                "Bearer": ACCESS_TOKEN,
            },
        )
        content = response.json()
        certificates.extend(content["certificates"])
        next_page_token = content["nextPageToken"]

    return certificates


def list_warrants(investment_firm_id: str) -> list[dict[str, Any]]:
    warrants = []

    response = requests.get(
        f"https://api.carta.com/v1alpha1/investors/firms/{investment_firm_id}/funds/-/investments/-/warrants",
        headers={
            "Bearer": ACCESS_TOKEN,
        },
    )
    content = response.json()
    warrants.extend(content["warrants"])
    next_page_token = content["nextPageToken"]

    while next_page_token:
        response = requests.get(
            f"https://api.carta.com/v1alpha1/investors/firms/{investment_firm_id}/funds/-/investments/-/warrants?pageToken={next_page_token}",
            headers={
                "Bearer": ACCESS_TOKEN,
            },
        )
        content = response.json()
        warrants.extend(content["warrants"])
        next_page_token = content["nextPageToken"]

    return warrants


def list_convertible_notes(investment_firm_id: str) -> list[dict[str, Any]]
    convertible_notes = []

    response = requests.get(
        f"https://api.carta.com/v1alpha1/investors/firms/{investment_firm_id}/funds/-/investments/-/convertibleNotes",
        headers={
            "Bearer": ACCESS_TOKEN,
        },
    )
    content = response.json()
    convertible_notes.extend(content["convertibleNotes"])
    next_page_token = content["nextPageToken"]

    while next_page_token:
        response = requests.get(
            f"https://api.carta.com/v1alpha1/investors/firms/{investment_firm_id}/funds/-/investments/-/convertibleNotes?pageToken={next_page_token}",
            headers={
                "Bearer": ACCESS_TOKEN,
            },
        )
        content = response.json()
        convertible_notes.extend(content["convertibleNotes"])
        next_page_token = content["nextPageToken"]

    return convertible_notes


certificates = list_certificates(INVESTMENT_FIRM_ID)
warrants = list_warrants(INVESTMENT_FIRM_ID)
convertible_notes = list_convertible_notes(INVESTMENT_FIRM_ID)

investments = certificates + warrants + convertible notes

# Congratulations, you've listed all your investments! Process your investments as you see fit!
#
# Make sure to check the API documentation to see what are the available fields for each type of security.