Open Cap Stack V2.0 API Documentation

[urbantech]

Overview

This documentation provides detailed information on the API endpoints available in Open Cap Stack V2.0. The API follows RESTful principles and is designed to manage corporations, issuers, investors, securities, and capitalization tables. All endpoints require authentication via OAuth 2.0, and responses are returned in JSON format.

---

Authentication

Endpoint: /api/v2/auth/token
Method: POST
Description: Generate an OAuth 2.0 access token for API authentication.

Request:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

Response:

{
  "access_token": "your_access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

---

Corporations

1. List Corporations

Endpoint: GET /api/v2/corporations
Description: Retrieve a list of corporations that the authenticated user has access to.

Response:

{
  "corporations": [
    {
      "id": "611",
      "legalName": "MangoCart, Inc.",
      "doingBusinessAsName": "MangoCart",
      "website": "http://www.example.com/mangocart"
    }
  ],
  "nextPageToken": "ODMxMw=="
}

2. Get Corporation Details

Endpoint: GET /api/v2/corporations/{corporationId}
Description: Retrieve detailed information about a specific corporation.

Response:

{
  "corporation": {
    "id": "611",
    "legalName": "MangoCart, Inc.",
    "doingBusinessAsName": "MangoCart",
    "website": "http://www.example.com/mangocart",
    "incorporationDate": "2020-01-15",
    "stateOfIncorporation": "US-CA",
    "taxId": "94-1234567"
  }
}

3. Create Corporation

Endpoint: POST /api/v2/corporations
Description: Create a new corporation.

Request:

{
  "legalName": "New Corp, Inc.",
  "doingBusinessAsName": "NewCorp",
  "website": "http://www.newcorp.com",
  "incorporationDate": "2024-01-01",
  "stateOfIncorporation": "US-NY",
  "taxId": "12-3456789"
}

Response:

{
  "corporation": {
    "id": "612",
    "legalName": "New Corp, Inc.",
    "doingBusinessAsName": "NewCorp",
    "website": "http://www.newcorp.com",
    "incorporationDate": "2024-01-01",
    "stateOfIncorporation": "US-NY",
    "taxId": "12-3456789"
  }
}

4. Update Corporation

Endpoint: PUT /api/v2/corporations/{corporationId}
Description: Update the details of an existing corporation.

Request:

{
  "legalName": "Updated Corp, Inc.",
  "doingBusinessAsName": "UpdatedCorp",
  "website": "http://www.updatedcorp.com"
}

Response:

{
  "corporation": {
    "id": "611",
    "legalName": "Updated Corp, Inc.",
    "doingBusinessAsName": "UpdatedCorp",
    "website": "http://www.updatedcorp.com"
  }
}

---

Compensation

1. Get Compensation Benchmark Attributes

Endpoint: GET /api/v2/compensation/benchmarks/attributes
Description: Retrieve all valid compensation benchmark attributes based on a corporation's plan.

Response:

{
  "benchmarks_metadata": {
    "benchmarks_version_datetime": {
      "value": "2024-01-01T09:00:00.000000Z"
    }
  },
  "compensation_types": ["SALARY", "EQUITY_AS_FULLY_DILUTED_PERCENT"],
  "industries": ["All"],
  "percentiles": ["P25", "P50", "P75"],
  "post_money_valuation_buckets": ["10M to 25M", "50M to 100M"],
  "geo_adjustment_location": ["Dallas-Fort Worth-Arlington, TX", "New York-Newark-Jersey City, NY-NJ-PA", "San Francisco-Oakland-Hayward, CA"],
  "jobs": [
    {
      "job_area": "Engineering",
      "job_specialization": "Web Engineer",
      "job_levels": ["IC 2", "IC 3", "MGR 4", "MGR 5", "EX 10", "EX 11"]
    }
  ]
}

2. Get Compensation Benchmarks

Endpoint: GET /api/v2/compensation/benchmarks
Description: Retrieve all compensation benchmarks based on a corporation's compensation plan.

Response:

{
  "access": {
    "access_level": "FULL_ACCESS",
    "access_reason": ""
  },
  "benchmarks_metadata": {
    "benchmarks_version_datetime": {
      "value": "2024-01-01T09:00:00.000000Z"
    }
  },
  "benchmarks": [
    {
      "post_money_valuation_bucket": "100M to 250M",
      "industry": "All",
      "geo_adjustment_location": "New York-Newark-Jersey City, NY-NJ-PA",
      "job_area": "Engineering",
      "job_specialization": "Web Engineer",
      "job_level": "IC 3",
      "benchmark_values": [
        {
          "compensation_type": "SALARY",
          "percentile": "P25",
          "benchmark": {
            "value": "100000"
          }
        }
      ]
    }
  ]
}

---

Issuers

1. List Issuers

Endpoint: GET /api/v2/issuers
Description: Retrieve a list of issuers.

Response:

{
  "issuers": [
    {
      "id": "611",
      "legalName": "MangoCart, Inc.",
      "doingBusinessAsName": "MangoCart",
      "website": "http://www.example.com/mangocart"
    }
  ],
  "nextPageToken": "ODMxMw=="
}

2. Get Issuer Details

Endpoint: GET /api/v2/issuers/{issuerId}
Description: Retrieve details of a specific issuer.

Response:

{
  "issuer": {
    "id": "611",
    "legalName": "MangoCart, Inc.",
    "doingBusinessAsName": "MangoCart",
    "website": "http://www.example.com/mangocart"
  }
}

3. Create Issuer

Endpoint: POST /api/v2/issuers
Description: Create a new issuer.

Request:

{
  "legalName": "New Issuer, Inc.",
  "doingBusinessAsName": "NewIssuer",
  "website": "http://www.newissuer.com"
}

Response:

{
  "issuer": {
    "id": "612",
    "legalName": "New Issuer, Inc.",
    "doingBusinessAsName": "NewIssuer",
    "website": "http://www.newissuer.com"
  }
}

4. Update Issuer

Endpoint: PUT /api/v2/issuers/{issuerId}
Description: Update the details of an existing issuer.

Request:

{
  "legalName": "Updated Issuer, Inc.",
  "doingBusinessAsName": "UpdatedIssuer",
  "website": "http://www.updatedissuer.com"
}

Response:

{
  "issuer": {
    "id": "611",
    "legalName": "Updated Issuer, Inc.",
    "doingBusinessAsName": "UpdatedIssuer",
    "website": "http://www.updatedissuer.com"
  }
}

---

Investors

1. List Firms

Endpoint: GET /api/v2/investors/firms
Description: Retrieve a list of investment firms.

Response:

{
  "firms": [
    {
      "id": "7af7123a-2ee9-4e31-a173-54b8f9159426",
      "name": "Krakatoa Ventures"
    }
  ],
  "nextPageToken": "ODMxMw=="
}

2. List Funds

Endpoint: GET /api/v2/investors/firms/{firmId}/funds
Description: Retrieve the investment funds of a given investment firm.

Response:

{
  "funds": [
    {
      "firm_id": "7af7123a-2ee9-4e31

-a173-54b8f9159426",
      "id": "d71529d5-56b1-49aa-9aa5-7d66a09d9ab3",
      "name": "Fund A"
    }
  ],
  "nextPageToken": "ODMxMw=="
}

---

Securities

1. List Securities

Endpoint: GET /api/v2/securities
Description: Retrieve a list of securities.

Response:

{
  "securities": [
    {
      "id": "1183",
      "class": "Common",
      "classDescription": "Common Stock",
      "classType": "EQUITY",
      "amountOutstanding": "1000000"
    }
  ],
  "nextPageToken": "ODMxMw=="
}

2. Get Security Details

Endpoint: GET /api/v2/securities/{securityId}
Description: Retrieve detailed information about a specific security.

Response:

{
  "security": {
    "id": "1183",
    "class": "Common",
    "classDescription": "Common Stock",
    "classType": "EQUITY",
    "amountOutstanding": "1000000"
  }
}

---

Capitalization Tables

1. Get Capitalization Table

Endpoint: GET /api/v2/capitalization-tables/{capTableId}
Description: Retrieve the capitalization table for a corporation as of a specific date.

Response:

{
  "capTable": {
    "id": "53bd35b5-95d0-4185-96f6-1b748b69f8ea",
    "issuerId": "d68e5604-6107-4f56-baf1-4cc09d7d0c50",
    "asOfDate": "2024-01-01",
    "fullyDilutedShares": "2000000",
    "outstandingShares": "1500000",
    "cashRaised": "10000000",
    "shareClassSummaries": [
      {
        "shareClassID": "CS-10",
        "outstandingShares": "1000000",
        "fullyDilutedShares": "1200000",
        "cashRaised": "8000000"
      }
    ],
    "optionPoolSummaries": [
      {
        "optionPoolId": "OP-15",
        "shareClassId": "CS-10",
        "fullyDilutedShares": "500000",
        "outstandingEquityAwardDerivatives": "300000"
      }
    ],
    "warrantBlockSummaries": [
      {
        "warrantBlockId": "WB-01",
        "shareClassId": "CS-10",
        "fullyDilutedShares": "500000",
        "outstandingWarrants": "200000"
      }
    ],
    "noteBlockSummaries": [
      {
        "noteBlockId": "NB-03",
        "principal": "500000",
        "interest": "50000",
        "outstanding_debt": "550000"
      }
    ]
  }
}

---

Error Handling

All API responses include appropriate HTTP status codes:

• 200 OK: The request was successful.
• 201 Created: A new resource has been successfully created.
• 204 No Content: The request was successful, but there is no content to return.
• 400 Bad Request: The request could not be understood or was missing required parameters.
• 401 Unauthorized: Authentication failed or the user does not have permissions for the requested operation.
• 404 Not Found: The requested resource could not be found.
• 500 Internal Server Error: An error occurred on the server.

Error Response Example:

{
  "error": {
    "code": "401",
    "message": "Unauthorized: Access is denied due to invalid credentials."
  }
}

---

Versioning

This API uses versioning in the URL to manage different versions (e.g., /api/v2/). This allows for backward compatibility and smooth transitions when new features or changes are introduced.

---

Rate Limiting

The API enforces rate limiting to ensure fair use and prevent abuse. The rate limit headers include:

• X-RateLimit-Limit: The maximum number of requests that the consumer is permitted to make in an hour.
• X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
• X-RateLimit-Reset: The time at which the rate limit window resets.