How to Use the Company Endpoint in the Claude API: A Practical Guide

If you're managing a team or organization using Claude AI, the Company endpoint in the Claude API is your go-to resource for handling organizational-level data. Whether you need to retrieve billing information, update company settings, or manage team members, this endpoint simplifies the process.

In this guide, you'll learn how to:

• Authenticate requests to the Company endpoint
• Retrieve company and billing details
• Update organizational settings programmatically
• Handle common errors and edge cases

Let's dive in.

What Is the Company Endpoint?

The Company endpoint (/v1/organizations/{organization_id}/company) allows you to interact with your organization's profile and settings within the Claude ecosystem. It's particularly useful for:

• Billing management: Retrieve usage and invoice data
• Team configuration: Update company-wide settings
• Compliance: Access audit logs and organizational metadata

This endpoint is available to users with admin-level API keys. If you're using a personal key, you'll need to upgrade to an organizational key to access these features.

Prerequisites

Before you start, make sure you have:

• A Claude API key with admin privileges
• Your organization ID (found in the Claude dashboard under Settings > Organization)
• Basic familiarity with REST APIs and your preferred programming language

Authentication

All requests to the Company endpoint require authentication via the x-api-key header. Here's how to set it up in Python and TypeScript:

Python Example

import requests
API_KEY = "your-api-key-here"
ORGANIZATION_ID = "your-org-id-here"
BASE_URL = "https://api.anthropic.com/v1"
headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}
def get_company_info():
    url = f"{BASE_URL}/organizations/{ORGANIZATION_ID}/company"
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return None
company_data = get_company_info()
print(company_data)

TypeScript Example

const API_KEY = "your-api-key-here";
const ORGANIZATION_ID = "your-org-id-here";
const BASE_URL = "https://api.anthropic.com/v1";
async function getCompanyInfo() {
  const url = ${BASE_URL}/organizations/${ORGANIZATION_ID}/company;
  
  const response = await fetch(url, {
    method: "GET",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json"
    }
  });
if (response.ok) {
    const data = await response.json();
    console.log(data);
    return data;
  } else {
    console.error(Error: ${response.status} - ${await response.text()});
    return null;
  }
}
getCompanyInfo();

Retrieving Company Details

Once authenticated, you can retrieve your company's profile information. The response typically includes:

• id: Unique identifier for the company
• name: Company name
• billing_email: Email address for billing communications
• created_at: Timestamp of when the company was registered
• settings: Object containing company-wide preferences

Example Response

{
  "id": "comp_abc123",
  "name": "Acme Corp",
  "billing_email": "[email protected]",
  "created_at": "2024-01-15T10:30:00Z",
  "settings": {
    "rate_limit": 1000,
    "max_users": 50,
    "feature_flags": ["advanced_analytics", "custom_models"]
  }
}

Updating Company Settings

You can update certain company settings using a PATCH request. This is useful for changing billing emails or adjusting rate limits.

Python Example

def update_company_settings(new_settings):
    url = f"{BASE_URL}/organizations/{ORGANIZATION_ID}/company"
    response = requests.patch(url, headers=headers, json=new_settings)
    
    if response.status_code == 200:
        print("Settings updated successfully")
        return response.json()
    else:
        print(f"Update failed: {response.status_code} - {response.text}")
        return None
Example: Update billing email
update_company_settings({
    "billing_email": "[email protected]"
})

TypeScript Example

async function updateCompanySettings(newSettings: object) {
  const url = ${BASE_URL}/organizations/${ORGANIZATION_ID}/company;
  
  const response = await fetch(url, {
    method: "PATCH",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(newSettings)
  });
if (response.ok) {
    const data = await response.json();
    console.log("Settings updated successfully", data);
    return data;
  } else {
    console.error(Update failed: ${response.status} - ${await response.text()});
    return null;
  }
}
// Example: Update billing email
updateCompanySettings({
  billing_email: "[email protected]"
});

Handling Errors

The Company endpoint returns standard HTTP status codes. Here are the most common ones you'll encounter:

Error Handling Example (Python)

def safe_get_company_info():
    try:
        url = f"{BASE_URL}/organizations/{ORGANIZATION_ID}/company"
        response = requests.get(url, headers=headers, timeout=10)
        response.raise_for_status()  # Raises exception for 4xx/5xx
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 403:
            print("Access denied: Check your API key permissions.")
        elif e.response.status_code == 429:
            print("Rate limited: Wait and retry.")
        else:
            print(f"HTTP error: {e}")
    except requests.exceptions.ConnectionError:
        print("Connection error: Check your network.")
    except requests.exceptions.Timeout:
        print("Request timed out.")
    return None

Best Practices

• Cache responses: Company data doesn't change frequently. Cache the response for 5-10 minutes to reduce API calls.
• Use environment variables: Store your API key and organization ID in environment variables, not in code.
• Implement retry logic: For transient errors (429, 500), use exponential backoff.
• Validate inputs: When updating settings, validate the data before sending to avoid unnecessary API calls.

Caching Example (Python)

import time
class CompanyCache:
    def __init__(self, ttl=300):  # 5 minutes TTL
        self.cache = None
        self.timestamp = 0
        self.ttl = ttl
    
    def get_company_info(self):
        if time.time() - self.timestamp > self.ttl or self.cache is None:
            self.cache = safe_get_company_info()
            self.timestamp = time.time()
        return self.cache
cache = CompanyCache()
info = cache.get_company_info()

Real-World Use Cases

Automating Billing Reports

Use the Company endpoint to fetch billing details and generate monthly reports:

def generate_billing_report():
    company = get_company_info()
    if company:
        report = f"""
        Billing Report for {company['name']}
        Billing Email: {company['billing_email']}
        Created: {company['created_at']}
        Current Rate Limit: {company['settings']['rate_limit']}
        """
        # Save to file or send via email
        with open("billing_report.txt", "w") as f:
            f.write(report)
        print("Report generated.")

Syncing Company Settings Across Teams

If you manage multiple teams, you can use the endpoint to ensure consistent settings:

def sync_settings_across_orgs(org_ids, new_settings):
    for org_id in org_ids:
        url = f"{BASE_URL}/organizations/{org_id}/company"
        response = requests.patch(url, headers=headers, json=new_settings)
        if response.status_code == 200:
            print(f"Organization {org_id} updated.")
        else:
            print(f"Failed to update {org_id}: {response.status_code}")

Limitations

• The Company endpoint is read-only for non-admin users. Only admin API keys can modify settings.
• Rate limits apply: default is 100 requests per minute for most organizations.
• Some settings (like feature_flags) may be immutable and require Anthropic support to change.

Key Takeaways

• The Company endpoint (/v1/organizations/{org_id}/company) lets you manage organizational settings and billing info programmatically.
• Authentication requires an admin-level API key passed via the x-api-key header.
• Common operations include retrieving company details (GET) and updating settings (PATCH).
• Error handling is critical: watch for 403 (permissions) and 429 (rate limits) specifically.
• Best practices include caching responses, using environment variables for credentials, and implementing retry logic for transient errors.

By mastering the Company endpoint, you can automate organizational management tasks, reduce manual overhead, and keep your Claude AI deployment running smoothly. Start integrating it into your workflows today!