API Cookbook

This cookbook provides practical examples for common API integration patterns. All examples require authentication - see the API Setup guide for details.

Prerequisites

Before using these examples, ensure you have:

An OAuth application created in your Standard Metrics settings
Your client_id and client_secret credentials
Python 3.9+ with requests library installed

Quick Start: Authentication

All API requests require a Bearer token. Here’s how to authenticate:

import requests
import base64

def get_access_token(client_id: str, client_secret: str) -> str:
    """Get access token from Standard Metrics API."""
    # Encode credentials
    credential = f"{client_id}:{client_secret}"
    encoded_credential = base64.b64encode(credential.encode("utf-8")).decode("utf-8")
    
    # Get access token
    response = requests.post(
        "https://api.standardmetrics.io/o/token/",
        headers={
            "Authorization": f"Basic {encoded_credential}",
            "Content-Type": "application/x-www-form-urlencoded",
        },
        data={"grant_type": "client_credentials"}
    )
    response.raise_for_status()
    
    return response.json()["access_token"]

# Usage
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"

access_token = get_access_token(client_id, client_secret)
headers = {"Authorization": f"Bearer {access_token}"}

1. Working with Companies

Get All Portfolio Companies

Retrieve all companies in your portfolio with pagination support:

def get_all_companies(headers: dict[str, str]) -> list[dict]:
    """Fetch all companies with pagination handling."""
    all_companies = []
    url = "https://api.standardmetrics.io/v1/companies/"
    
    while url:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        
        data = response.json()
        all_companies.extend(data.get("results", []))
        url = data.get("next")  # Handle pagination
    
    return all_companies

# Usage
companies = get_all_companies(headers)
print(f"Found {len(companies)} companies")

# Create a name-to-ID mapping for easy lookup
company_map = {company["name"]: company["id"] for company in companies}

Create a New Company

Add a new company to your portfolio:

def create_company(headers: dict[str, str], company_data: dict) -> dict:
    """Create a new company in your portfolio."""
    response = requests.post(
        "https://api.standardmetrics.io/v1/companies/",
        headers=headers,
        json=company_data
    )
    response.raise_for_status()
    return response.json()

# Example usage
new_company = {
    "name": "Acme Corp",
    "website": "https://acme.com",
    "description": "Technology company",
    "stage": "Series A"
}

company = create_company(headers, new_company)
print(f"Created company '{company['name']}' with ID: {company['id']}")

2. Fetching Metrics

Get Metrics for a Single Company

Retrieve financial metrics for a specific company:

def get_company_metrics(headers: dict[str, str], company_id: str, **filters) -> list[dict]:
    """Get metrics for a specific company with optional filters."""
    params = {"company_id": company_id}
    params.update(filters)
    
    response = requests.get(
        "https://api.standardmetrics.io/v1/metrics/",
        headers=headers,
        params=params
    )
    response.raise_for_status()
    
    return response.json().get("results", [])

# Example: Get revenue and cash metrics for the last year
company_id = "your_company_id_here"
metrics = get_company_metrics(
    headers, 
    company_id,
    category=["revenue", "cash_in_bank"],
    cadence="month",
    from_date="2023-01-01",
    to_date="2023-12-31"
)

print(f"Retrieved {len(metrics)} metric records")

# Process the results
for metric in metrics:
    print(f"{metric['category']}: ${metric['value']} on {metric['date']}")

Get Metrics for Multiple Companies

Fetch metrics across your entire portfolio:

from collections import defaultdict

def get_portfolio_metrics(headers: dict[str, str], **filters) -> list[dict]:
    """Get metrics for all companies in portfolio with pagination."""
    all_metrics = []
    url = "https://api.standardmetrics.io/v1/metrics/"
    params = filters
    
    while url:
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()
        
        data = response.json()
        all_metrics.extend(data.get("results", []))
        
        url = data.get("next")
        params = {}  # Clear params for subsequent pages
    
    return all_metrics

# Example: Get latest revenue for all companies
portfolio_metrics = get_portfolio_metrics(
    headers,
    category="revenue",
    cadence="month",
    limit=100
)

print(f"Retrieved {len(portfolio_metrics)} metrics across portfolio")

# Group by company
metrics_by_company = defaultdict(list)
for metric in portfolio_metrics:
    metrics_by_company[metric["company_id"]].append(metric)

3. Working with Documents

Fetch Company Documents

Retrieve documents associated with companies:

def get_company_documents(headers: dict[str, str], company_id: str = None, **filters) -> list[dict]:
    """Get documents, optionally filtered by company and criteria."""
    params = filters.copy()
    if company_id:
        params["company_id"] = company_id
    
    response = requests.get(
        "https://api.standardmetrics.io/v1/documents/",
        headers=headers,
        params=params
    )
    response.raise_for_status()
    
    return response.json().get("results", [])

# Get all documents for a specific company
company_id = "your_company_id_here"
documents = get_company_documents(headers, company_id)
print(f"Found {len(documents)} documents for company")

# Get financial statements only
financial_docs = get_company_documents(
    headers, 
    company_id, 
    document_type="financial_statement"
)
print(f"Found {len(financial_docs)} financial statements")

Upload a Document

Add new documents to the system:

def upload_document(headers: dict[str, str], document_data: dict) -> dict:
    """Upload a new document to the system."""
    response = requests.post(
        "https://api.standardmetrics.io/v1/documents/",
        headers=headers,
        json=document_data
    )
    response.raise_for_status()
    return response.json()

# Example usage
document = {
    "company_id": "your_company_id_here",
    "title": "Q4 2023 Financial Report",
    "document_type": "financial_statement",
    "url": "https://example.com/q4-report.pdf",
    "date": "2023-12-31"
}

uploaded_doc = upload_document(headers, document)
print(f"Uploaded document '{uploaded_doc['title']}' with ID: {uploaded_doc['id']}")

4. Pushing Metrics

Submit New Metrics

Push custom metrics to Standard Metrics:

def push_metrics(headers: dict[str, str], company_id: str, metrics: list[dict]) -> dict:
    """Push new metrics to Standard Metrics."""
    payload = {
        "company_id": company_id,
        "metrics": metrics
    }
    
    response = requests.post(
        "https://api.standardmetrics.io/v1/metrics/",
        headers=headers,
        json=payload
    )
    response.raise_for_status()
    return response.json()

# Example: Push monthly revenue data
metrics_data = [
    {
        "category": "revenue",
        "value": 150000,
        "date": "2023-10-31",
        "cadence": "month",
        "currency": "USD"
    },
    {
        "category": "revenue",
        "value": 162000,
        "date": "2023-11-30",
        "cadence": "month",
        "currency": "USD"
    }
]

company_id = "your_company_id_here"
result = push_metrics(headers, company_id, metrics_data)

5. Complete Integration Example

Here’s a comprehensive example that combines multiple API operations:

import base64

class StandardMetricsClient:
    """Simple client for Standard Metrics API."""
    
    def __init__(self, client_id: str, client_secret: str):
        """Initialize client with OAuth credentials."""
        self.headers = self._get_headers(client_id, client_secret)
    
    def _get_headers(self, client_id: str, client_secret: str) -> dict[str, str]:
        """Get authorization headers."""
        access_token = get_access_token(client_id, client_secret)
        return {"Authorization": f"Bearer {access_token}"}
    
    def get_companies(self) -> list[dict]:
        """Get all companies in portfolio."""
        return get_all_companies(self.headers)
    
    def get_metrics(self, company_id: str, **filters) -> list[dict]:
        """Get metrics for a company with optional filters."""
        return get_company_metrics(self.headers, company_id, **filters)
    
    def push_metrics(self, company_id: str, metrics: list[dict]) -> dict:
        """Push new metrics for a company."""
        return push_metrics(self.headers, company_id, metrics)

# Usage example
client = StandardMetricsClient("your_client_id", "your_client_secret")

# Get companies
companies = client.get_companies()
print(f"Found {len(companies)} companies")

# Get metrics for first company
if companies:
    company = companies[0]
    
    metrics = client.get_metrics(
        company["id"],
        category="revenue",
        cadence="month",
        from_date="2023-01-01",
        to_date="2023-12-31"
    )
    
    print(f"Found {len(metrics)} revenue metrics for {company['name']}")
    
    # Push new metric
    new_metrics = [{
        "category": "revenue",
        "value": 200000,
        "date": "2023-12-31",
        "cadence": "month",
        "currency": "USD"
    }]
    
    result = client.push_metrics(company["id"], new_metrics)

Error Handling

Always implement proper error handling in your integrations:

import requests
import time

def safe_api_call(func, *args, max_retries: int = 3, base_delay: float = 1.0, max_delay: float = 60.0, **kwargs) -> requests.Response:
    """
    Always raises on failure.

    Success: any 2xx -> returns the Response.
    Retries: 429, 5xx, Timeout, RequestException (exponential backoff, no jitter).
    Fails fast: 3xx (unexpected redirect) and other 4xx except 429.
    """
    last_exc = None

    for attempt in range(max_retries + 1):
        try:
            resp = func(*args, **kwargs)
            code = resp.status_code

            if 200 <= code < 300:
                return resp

            # Retry on 429 and 5xx
            if code == 429 or 500 <= code < 600:
                if attempt < max_retries:
                    delay = min(base_delay * (2 ** attempt), max_delay)
                    time.sleep(delay)
                    continue
                resp.raise_for_status()

            resp.raise_for_status()

        except (requests.exceptions.Timeout, requests.exceptions.RequestException) as e:
            if attempt < max_retries:
                delay = min(base_delay * (2 ** attempt), max_delay)
                time.sleep(delay)
                continue
            raise

    raise RuntimeError("safe_api_call: exhausted attempts without a response")


# Usage example
resp = safe_api_call(
    requests.get,
    "https://api.standardmetrics.io/v1/companies/",
    headers=headers,
    timeout=30
)

result = resp.json()
companies = result.get("results", [])
print(f"Successfully fetched {len(companies)} companies")

Rate Limits

The API has a limit of 30 requests per 10 seconds per bearer token. For high-volume integrations, implement backoff logic:

pip install tenacity

import requests
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10),
    retry=retry_if_exception_type(requests.exceptions.RequestException)
)
def fetch_company_data(company_id: str, headers: dict[str, str]) -> dict:
    """Fetch company data with automatic retry logic."""
    response = requests.get(
        f"https://api.standardmetrics.io/v1/companies/{company_id}/",
        headers=headers,
        timeout=30
    )
    response.raise_for_status()
    return response.json()
        print(f"Error fetching {company_id}: {e}")

Next Steps

Explore the full API Reference for detailed endpoint documentation
Set up MCP integration for advanced automation within Claude and other MCP clients

Need help? Visit our Support Center or contact our team for integration assistance.

Welcome

User Guides

MCP Setup

Auth

Usage

Budgets

Companies

Custom Columns

Documents

Funds

Information Reports

Information Requests

Investment Details (Beta)

Metrics

Notes

Users

Prerequisites

Quick Start: Authentication

1. Working with Companies

Get All Portfolio Companies

Create a New Company

2. Fetching Metrics

Get Metrics for a Single Company

Get Metrics for Multiple Companies

3. Working with Documents

Fetch Company Documents

Upload a Document

4. Pushing Metrics

Submit New Metrics

5. Complete Integration Example

Error Handling

Rate Limits

Next Steps

​Prerequisites

​Quick Start: Authentication

​1. Working with Companies

​Get All Portfolio Companies

​Create a New Company

​2. Fetching Metrics

​Get Metrics for a Single Company

​Get Metrics for Multiple Companies

​3. Working with Documents

​Fetch Company Documents

​Upload a Document

​4. Pushing Metrics

​Submit New Metrics

​5. Complete Integration Example

​Error Handling

​Rate Limits

​Next Steps

Prerequisites

Quick Start: Authentication

1. Working with Companies

Get All Portfolio Companies

Create a New Company

2. Fetching Metrics

Get Metrics for a Single Company

Get Metrics for Multiple Companies

3. Working with Documents

Fetch Company Documents

Upload a Document

4. Pushing Metrics

Submit New Metrics

5. Complete Integration Example

Error Handling

Rate Limits

Next Steps