# Generated by tools/build_contracts.py from tools/algoseek_catalog.py -- do not edit by hand. # Open Data Contract Standard v3.2.0 (https://bitol-io.github.io/open-data-contract-standard/). apiVersion: v3.2.0 kind: DataContract id: urn:alphaswarm:datacontract:algoseek:us-equities-ipo-detailed name: AlgoSeek US Equities IPO Detailed version: 0.1.0 status: draft domain: market-data tags: - algoseek - licensed-data - equity - reference - us - event description: purpose: 'The basic IPO record per security plus offering-level metadata: security description, par value and currency, offer price range, final and first listing prices, underwriter, deal type, law firm and transfer agent. Used for IPO structure and pricing research and security-master enrichment.' usage: Point-in-time security identity, corporate-action adjustment, and universe construction for US equities. limitations: 'Vendor-curated reference data: rows can be restated when AlgoSeek learns of a late or corrected event, so land each delivery as a snapshot rather than overwriting history. Row grain is one mutable record per security: the guide says each row is an individual security record and the file is rewritten (3 times daily) whenever an IPO event is new or modified, so a point-in-time history of Status transitions is NOT retained in the file; snapshot it yourself if you need as-of replay. CreatedDate = trading date the record first appeared; ModifiedDate = trading date of the last change with an optional _n version suffix (basic sample uses _1/_2/_3; many detailed-sample rows carry a bare yyyymmdd). Treat ModifiedDate as a string, not a date. Status NEW and HISTORY are date-driven (NEW while listing date is today/yesterday, HISTORY once it is more than 2 days old), so a record''s Status can change without a new IPO event; the lifecycle in the guide is RUMOUR -> PENDING -> NEW -> HISTORY, with POSTPONED, WITHDRAWN and DLP as other outcomes. SecId is algoseek''s security id and is already assigned to PENDING/POSTPONED IPOs; USIdentifier, ISIN and FirstTradingDate are blank until known (basic sample: blank in 68, 66 and 75 of 100 rows respectively).' authoritativeDefinitions: - type: businessDefinition url: https://algoseek.com/dataset/us-equities-ipo-detailed/ - type: implementation url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.IPO.pdf - type: implementation url: https://algoseek.com/docs/rest-api/reference context: instructions: Rows are effective-dated. Answer point-in-time questions with the row in force on the as-of date, never the latest row. SecId and ASID are both durable AlgoSeek security keys but different values (the ASID lookup links them); tickers are reused across companies, so resolve a ticker to a key with a trade date. constraints: - id: c1 constraint: 'Licensed vendor data: never export raw rows to a tenant-local destination or include them verbatim in a public artifact; serve only through entitlement-checked platform reads.' - id: c3 constraint: Do not treat the vendor's `Ticker` as a stable identity across time; join on an AlgoSeek security key (SecId or ASID, which are distinct) or the platform symbol mapping. servers: - server: algoseek-s3 type: s3 environment: vendor description: AlgoSeek flat-file delivery (the layout the schema below describes). location: s3://${ALGOSEEK_S3_BUCKET_EQ_IPO_DETAILED}/ format: csv encoding: UTF-8 customProperties: - property: layout value: Single CSV file (ipo_detailed.csv per guide; the published sample file is named eq_ipo.csv) with a fixed header; one row per security record. The basic variant is a separate file (ipo_basic.csv). - property: compression value: gzip - property: header value: true - property: entitlement value: Bucket access is granted per subscription; bucket names arrive with license provisioning. - server: algoseek-rest-api type: api environment: vendor description: AlgoSeek Datasets REST API (X-API-KEY header; JSON, CSV or gzipped CSV). Returns AlgoSeek's normalized API layout, which differs from the flat-file columns in this contract's schema. location: https://api.algoseek.com/v1/data/us-equity-ref/ipo-detailed customProperties: - property: auth value: X-API-KEY header issued by AlgoSeek - property: columnsEndpoint value: https://api.algoseek.com/v1/meta/datasets/{dataset_id}/columns - property: statusEndpoint value: https://api.algoseek.com/v1/meta/datasets/{dataset_id}/status - property: responseFormats value: - json - csv - csv_gzip - property: pagination value: offset + limit; tick endpoints take trade_date and identifier (Ticker or ASID) in the path schema: - name: us_equities_ipo_detailed physicalName: eq_ipo_detailed physicalType: file logicalType: object businessName: US Equities IPO Detailed description: 'The basic IPO record per security plus offering-level metadata: security description, par value and currency, offer price range, final and first listing prices, underwriter, deal type, law firm and transfer agent. Used for IPO structure and pricing research and security-master enrichment.' dataGranularityDescription: one IPO record per security (SecId), updated in place as the IPO progresses properties: - name: CreatedDate logicalType: date logicalTypeOptions: format: yyyymmdd physicalType: string (yyyymmdd) (csv text) description: Trading date on which the IPO record was first created. customProperties: - property: nullMeaning value: unstated (always populated in sample) - property: evidence value: guide+sample - name: ModifiedDate logicalType: string logicalTypeOptions: format: yyyymmdd[_n] physicalType: string (yyyymmdd[_n]) (csv text) description: Trading date of the latest update plus optional _n suffix; 86 of 100 sample rows are a bare yyyymmdd (20230925). customProperties: - property: nullMeaning value: unstated (always populated in sample) - property: evidence value: guide+sample - name: SecId logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: algoseek unique security identifier. primaryKey: true primaryKeyPosition: 1 required: true customProperties: - property: nullMeaning value: unstated (always populated in sample) - property: evidence value: guide+sample - name: Ticker logicalType: string physicalType: string (csv text) description: Symbol name; can be blank before a ticker is assigned. customProperties: - property: nullMeaning value: unstated; blank in 3 of 100 sample rows - property: evidence value: guide+sample - name: Name logicalType: string physicalType: string (csv text) description: Security name. customProperties: - property: nullMeaning value: unstated (always populated in sample) - property: evidence value: guide+sample - name: SecDescription logicalType: string logicalTypeOptions: format: free text, e.g. 'Ordinary Shares' or 'Units (1 Ord Class A & 1 War)' physicalType: string (csv text) description: Free-text description of the offered security type (shares, units, ADR). customProperties: - property: nullMeaning value: unstated (always populated in sample) - property: evidence value: guide+sample - name: ParValue logicalType: number physicalType: decimal (csv text) description: Par value of the security; blank for units and many others. customProperties: - property: nullMeaning value: unstated; blank in 58 of 100 sample rows - property: evidence value: guide+sample - name: PVCurrency logicalType: string logicalTypeOptions: format: ISO currency code physicalType: string (csv text) description: ISO currency code of the par value (USD, CAD, HKD seen in sample). customProperties: - property: nullMeaning value: unstated (always populated in sample) - property: evidence value: guide+sample - name: SharePriceLowest logicalType: number physicalType: decimal (csv text) description: Lowest offer price during the IPO (price range low end); currency not stated. customProperties: - property: nullMeaning value: unstated; blank in 5 of 100 sample rows - property: evidence value: guide+sample - name: SharePriceHighest logicalType: number physicalType: decimal (csv text) description: Highest offer price during the IPO (price range high end); currency not stated. customProperties: - property: nullMeaning value: unstated; blank in 5 of 100 sample rows - property: evidence value: guide+sample - name: ProposedPrice logicalType: number physicalType: decimal (csv text) description: Guide describes it as the final issue price despite the 'Proposed' name; currency not stated. customProperties: - property: nullMeaning value: unstated; blank in 12 of 100 sample rows - property: evidence value: guide+sample - name: InitialPrice logicalType: number physicalType: decimal (csv text) description: First listing price per guide; empty in every sample row, including HISTORY rows. customProperties: - property: nullMeaning value: unstated; blank in all 100 sample rows - property: evidence value: guide+sample - name: USIdentifier logicalType: string logicalTypeOptions: format: 9-character CUSIP/CINS-style code (per sample) physicalType: string (csv text) description: Identifier for US securities; blank until assigned. customProperties: - property: nullMeaning value: unstated; blank in 14 of 100 sample rows - property: evidence value: guide+sample - name: ISIN logicalType: string logicalTypeOptions: format: 12-character ISIN physicalType: string (csv text) description: ISIN code. customProperties: - property: nullMeaning value: unstated; blank in 14 of 100 sample rows - property: evidence value: guide+sample - name: FirstTradingDate logicalType: date logicalTypeOptions: format: yyyymmdd physicalType: string (yyyymmdd) (csv text) description: First trading date; blank while the date is not yet set. customProperties: - property: nullMeaning value: unstated; blank in 30 of 100 sample rows - property: evidence value: guide+sample - name: Underwriter logicalType: string physicalType: string (csv text) description: Underwriter to the issue (single free-text name in sample). customProperties: - property: nullMeaning value: unstated; blank in 6 of 100 sample rows - property: evidence value: guide+sample - name: DealType logicalType: string physicalType: string (csv text) description: Underwriting level; only BOUGHTDEAL appears in the sample and values are not enumerated in the guide. customProperties: - property: nullMeaning value: unstated; blank in 3 of 100 sample rows - property: evidence value: guide+sample - name: LawFirm logicalType: string physicalType: string (csv text) description: Law firm company name; free text with stray punctuation in sample (trailing comma). customProperties: - property: nullMeaning value: unstated; blank in 2 of 100 sample rows - property: evidence value: guide+sample - name: TransferAgent logicalType: string physicalType: string (csv text) description: Transfer agent name; free text, spelling varies across rows. customProperties: - property: nullMeaning value: unstated; blank in 28 of 100 sample rows - property: evidence value: guide+sample - name: ExchangeCode logicalType: string physicalType: string (csv text) description: Code identifying the exchange of the IPO listing; values are not enumerated in the guide. customProperties: - property: nullMeaning value: unstated (always populated in sample) - property: evidence value: guide+sample - name: Status logicalType: string physicalType: string (csv text) description: Stage of the IPO event; see Status values. enum: - value: NEW label: IPO is complete or in action; listing date is today or yesterday - value: RUMOUR label: Company or another respected source announced intent to IPO, before necessary approval - value: PENDING label: IPO is confirmed and the necessary approval has been made - value: HISTORY label: IPO has taken place; listing date is more than 2 days earlier - value: POSTPONED label: IPO temporarily suspended pending further announcement on the placement - value: WITHDRAWN label: IPO permanently stopped by company or regulator decision - value: DLP label: Direct Listing Process customProperties: - property: nullMeaning value: unstated (always populated in sample) - property: evidence value: guide+sample quality: - id: row_count_positive metric: rowCount mustBeGreaterThan: 0 dimension: completeness severity: error description: Every delivered partition (trade date, or snapshot) carries at least one row. - id: primary_key_unique metric: duplicateValues mustBe: 0 arguments: properties: - SecId dimension: uniqueness severity: error description: The declared primary key is unique within each delivered partition (one file or table snapshot). support: - channel: algoseek-support tool: email url: mailto:support@algoseek.com scope: issues description: Vendor support for data defects, missing days, and entitlement problems. team: name: AlphaSwarm data engineering slaProperties: - id: retention property: retention value: license-term description: Retention of landed copies is bounded by the AlgoSeek license; purge on termination. driver: regulatory customProperties: - property: vendor value: AlgoSeek - property: vendorDataGroup value: us-equity-ref - property: vendorDatasetTextId value: eq_ipo_detailed - property: vendorSampleUrl value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_ipo.csv - property: assetClass value: equity - property: venues value: - USNASD - USNYSE - USAMEX - property: coverage value: 'Same universe as the basic IPO file: US market excluding OTC, sourced from local exchanges (primary) and news sources (secondary). Guide gives no history start; earliest CreatedDate in the 100-row sample is 20220104 (sample only).' - property: timezone value: America/New_York - property: timestampFormat value: yyyymmdd; ModifiedDate = yyyymmdd[_n] - property: priceAdjustment value: n/a - property: licensedData value: true - property: evidenceGrade value: vendor-doc - property: knownIssues value: - Primary key is inferred; AlgoSeek's guide does not name one. - 'Doc discrepancy: Guide says IPOs are captured at ''six different stages'' but Table 4 defines seven Status values.' - 'Doc discrepancy: Guide intro says the detailed version includes ''Shares Outstanding information'', but Table 3 and the sample header have no shares-outstanding column.' - 'Doc discrepancy: Guide names the detailed file ipo_detailed.csv; the published sample is named eq_ipo.csv.' - 'Doc discrepancy: Guide Table 3 describes ProposedPrice as ''Final Issue Price'' and InitialPrice as ''First Listing Price''; the names suggest the opposite emphasis and InitialPrice is empty in all 100 sample rows (even HISTORY rows).' - 'Doc discrepancy: ModifiedDate is documented as yyyymmdd[_n]; 86 of 100 sample rows have a bare yyyymmdd (20230925) with no _n suffix, whereas the basic sample always has a suffix.' - 'Doc discrepancy: Guide does not enumerate ExchangeCode or DealType values; sample shows USNASD/USNYSE/USAMEX and BOUGHTDEAL only.' - 'Doc discrepancy: Sample LawFirm/TransferAgent values contain stray punctuation and spelling variants (''Maples and Calder (Cayman) LLP,'', ''Vstock Transfer,'', ''Continental Stock Transfer & Trust Co'' vs ''... Company'').' contractCreatedTs: '2026-11-02T00:00:00Z'