Documentation Index
Fetch the complete documentation index at: https://docs.sacra.com/llms.txt
Use this file to discover all available pages before exploring further.
Executive summary
The Events API is introducing a final v1 schema to improve data accuracy, consistency, and clarity. This document outlines all changes between the legacy v0 MVP schema and the new v1 schema. v1 became the default on November 19.What’s changing
- Event type format: kebab-case to snake_case (
funding-roundtofunding_round) - Status terminology:
plannedtoannouncedfor clarity - Round type accuracy: Generic
equitytype split into specificgrowthandcrowdfundingtypes - Model separation:
CorporateActionnow distinct fromCompanyMilestone - New fields:
event_nameandevent_statusat envelope level,closing_datefor SecondaryTransactions,is_extensionfor FundingRounds
Migration timeline
- Current status: v1 is opt-in via
?version=v1query parameter - Default: v0 schema (for backward compatibility)
- Migration period: v1 default will be in effect November 19
- Future: v1 will become default (v0 will be deprecated but you can still query for v0)
Impact assessment
- Breaking changes: Yes — response format changes require client code updates
- Backward compatibility: v0 remains default during migration period
- Action required: Test with
?version=v1, update client code, migrate before deadline
Breaking changes
1. Event type format change
Event types have changed from kebab-case to snake_case for consistency with industry standards.| Entity | v0 (Legacy) | v1 |
|---|---|---|
| FundingRound | funding-round | funding_round |
| SecondaryTransaction | secondary-transaction | secondary_transaction |
| CorporateAction | company-milestone | corporate_action |
| CompanyMilestone | company-milestone | company_milestone |
event_type in responses must be updated.
The
types query parameter still uses kebab-case in both v0 and v1 (e.g. ?types=funding-round). Only the event_type field in the response changed to snake_case.In v0,
CorporateAction and CompanyMilestone were both returned as company-milestone. In v1, they are distinct types.2. Status field terminology
The status terminology has changed fromplanned to announced for better clarity about event lifecycle.
| Status meaning | v0 (Legacy) | v1 |
|---|---|---|
| Announced but not completed | planned | announced |
| Completed/finalized | closed | closed |
| Cancelled/abandoned | cancelled | cancelled |
3. Round type accuracy
v1 exposes accurate round types instead of generic mappings. The genericequity type has been split into specific types.
| Actual round type | v0 (Legacy) | v1 |
|---|---|---|
| Growth round | equity | growth |
| Crowdfunding | equity | crowdfunding |
| Strategic | strategic | strategic |
| Seed | seed | seed |
| Series A-N | series_a-series_n | series_a-series_n |
equity type no longer exists in v1. Clients filtering or processing by round type must update logic.
4. CorporateAction vs CompanyMilestone separation
v1 introduces a distinctCorporateAction entity type, separating capital structure changes from general company milestones.
v0: Both corporate actions (stock splits, recaps) and company milestones (IPOs, incorporations) returned as company-milestone.
v1: Distinct types:
corporate_action: Stock splits, reverse splits, recapitalizationscompany_milestone: IPOs, incorporations, delistings
types=company-milestone in v0 returned both. In v1, you must specify which type you want.
5. New field: event_status at envelope level
v1 adds event_status at the event envelope level (in addition to data.status) for easier filtering without parsing nested data.
6. New field: closing_date for SecondaryTransactions
v1 adds the closing_date field to SecondaryTransaction events to distinguish between announcement and completion dates.
Smart inference: If event_status: "closed" but closing_date is null, the API automatically sets closing_date = announced_date in the response (indicating “we know it closed, but only have one date”).
7. New field: event_name at envelope level
v1 adds event_name to the event envelope for easier timeline/visualization rendering without parsing nested data.
8. New field: is_extension for FundingRounds
v1 adds the is_extension boolean field to identify funding rounds that extend or follow on from a previous round.
Use cases:
- Identify multiple closes of the same series
- Calculate total capital by series (base + extensions)
- Detect reclassified growth rounds
Side-by-side field comparison
Event envelope fields
| Field | v0 | v1 | Notes |
|---|---|---|---|
event_id | Yes | Yes | Unchanged |
event_type | Yes (kebab-case) | Yes (snake_case) | Format changed |
event_subtype | Yes | Yes | May differ for round types |
event_name | No | Yes | New in v1 |
event_date | Yes | Yes | Unchanged |
event_status | No | Yes | New in v1 |
event_last_updated_at | Yes | Yes | Unchanged |
company | Yes | Yes | Unchanged |
data | Yes | Yes | Structure varies by type |
FundingRound data fields
| Field | v0 | v1 | Notes |
|---|---|---|---|
id | Yes | Yes | Unchanged |
name | Yes | Yes | Unchanged |
round_type | Yes (equity generic) | Yes (growth/crowdfunding specific) | More accurate in v1 |
amount_raised | Yes | Yes | Unchanged |
currency | Yes | Yes | Unchanged |
valuation | Yes | Yes | Unchanged |
announced_date | Yes | Yes | Unchanged |
equities | Yes | Yes | Unchanged |
status | Yes (planned) | Yes (announced) | Terminology changed |
is_extension | No | Yes | New in v1 |
created_at | Yes | Yes | Unchanged |
updated_at | Yes | Yes | Unchanged |
SecondaryTransaction data fields
| Field | v0 | v1 | Notes |
|---|---|---|---|
id | Yes | Yes | Unchanged |
name | Yes | Yes | Unchanged |
transaction_type | Yes | Yes | Unchanged |
transaction_amount | Yes | Yes | Unchanged |
currency | Yes | Yes | Unchanged |
valuation | Yes | Yes | Unchanged |
price_per_share | Yes | Yes | Unchanged |
announced_date | Yes | Yes | Unchanged |
closing_date | No | Yes | New in v1 |
status | Yes (planned) | Yes (announced) | Terminology changed |
created_at | Yes | Yes | Unchanged |
updated_at | Yes | Yes | Unchanged |
CorporateAction (v1) vs CompanyMilestone (v0)
In v0, corporate actions were returned ascompany-milestone with a simplified schema. In v1, they have their own distinct type and richer schema.
v0 schema (as company-milestone):
corporate_action):
event_typechanged fromcompany-milestonetocorporate_action- New
announced_datefield (separate fromeffective_date) - New
event_statusat envelope level namefield replaces simplifiedlabelstatusfield added to data
Complete migration example
v0 response (legacy)
Full v0 response for Ramp events
Full v0 response for Ramp events
v1 response
Full v1 response for Ramp events
Full v1 response for Ramp events