Data Formats & Structures
Purpose
This page explains how we deliver data, what formats we support, and the standard structures we use across projects. If you need a custom schema, we can adapt. Email henry@primechasedata.com.
Global Standards
- Encoding: UTF-8
- Timezone: UTC by default. Include timezone if not UTC.
- Dates: ISO 8601. Example: 2025-01-21T14:30:00Z
- Numbers: Dot as decimal separator
- Currency: 3-letter ISO code. Example: USD, KRW
- Booleans: true or false
- IDs: UUID v4 or your native platform ID. We include both when possible.
- Phone: E.164. Example: +14155551234, +821012345678
- Nulls: Empty string or null, not N/A or 0
- File naming: clientslug_object_YYYYMMDD.csv
- PII handling: Only fields listed below. Remove anything not required.
Delivery Methods
📄 CSV Export
- • UTF-8, comma separated
- • Header row included
- • Zipped if over 50k rows
- • One row per record
🔌 JSON API
- • REST endpoints with OAuth 2.0
- • Pagination via cursor
- • Rate limit: 100 requests/minute
- • Webhooks for delivery_ready and error events
📊 Google Sheets
- • Shared view-only sheet
- • Collaborative reviews
- • Version history retained
🔄 Direct CRM Sync
- • Salesforce, HubSpot via native connectors
- • Zapier integration available
- • Mapping done in shared data dictionary
Data Quality Standards
Every file includes a data_quality_report tab or JSON block with row counts, duplicates removed, and error reasons.
Key Objects and Schemas
1. Lead Object
Standard Fields
lead_id: String (UUID we assign) first_name: String last_name: String email: String (Verified) phone: String (E.164 format) title: String company: String company_id: String (Our internal ID) linkedin_url: URL country: String (ISO-2) state_region: String city: String source_system: String (e.g., "web_form", "import") verified_date: Date
Enrichment Fields
company_size: Integer (Employees) revenue: Number (Annual in USD) industry: String (NAICS or plain English) seniority: String (e.g., "Manager", "Director", "VP") department: String (e.g., "Marketing", "IT") engagement_status: String (e.g., "opened", "replied") last_engaged_at: DateTime intent_topics: Array of Strings
Deduplication: By email. If missing, use phone. If both missing, use normalized name + company + country hash.
2. Account (Company) Object
account_id: String company: String domain: String naics: String industry: String company_size: Integer revenue: Number hq_country: String hq_state_region: String hq_city: String linkedin_url: URL created_at: DateTime updated_at: DateTime
3. Location (Store/Office) Object
location_id: String account_id: String name: String address_1: String address_2: String city: String state_region: String postal_code: String country: String lat: Number lng: Number phone: String hours_json: JSON (daily hours) gbp_place_id: String (if available)
4. Product Object (E-commerce/Retail)
product_id: String
sku: String
barcode_gtin: String
name: String
category: String
price: Number
currency: String
case_pack: Integer
unit_weight_kg: Number
dimensions_cm_lwh: String ("LxWxH")
origin_country: String
hts_code: String (if known)
status: String ("active", "draft", "retired")5. Event Object
event_id: String event_name: String (e.g., "page_view", "purchase") occurred_at: DateTime UTC session_id: String user_id: String (if logged in) lead_id: String (if known) page_url: URL referrer_url: URL source: String medium: String campaign: String channel: String (mapped using our rules) value: Number currency: String
6. Campaign Performance Object
period_start: Date period_end: Date channel: String source: String medium: String campaign: String impressions: Integer clicks: Integer spend: Number conversions: Integer revenue: Number cpc: Number cpa: Number roas: Number
UTM and Channel Mapping
We normalize UTMs into a standard channel set:
If UTMs are missing, we infer channel by source and medium rules. We publish the full mapping table in your data dictionary.
Import Templates
Download Templates
Use our templates to ensure smooth data import into your systems:
Sample Data
Sample CSV (Leads)
lead_id,first_name,last_name,email,phone,company,title,country,verified_date c6f2…,Jin,Park,jin.park@example.com,+821012345678,Acme Co,Marketing Manager,KR,2025-01-18 1a9b…,Sara,Kim,sara.kim@example.com,+12025550123,Acme USA,Director,US,2025-01-18
Sample JSON (Performance)
{
"period_start": "2025-01-01",
"period_end": "2025-01-31",
"channel": "Paid Search",
"source": "google",
"medium": "cpc",
"campaign": "brand_us",
"impressions": 120000,
"clicks": 6800,
"spend": 14500.75,
"conversions": 420,
"revenue": 62500,
"cpc": 2.13,
"cpa": 34.52,
"roas": 4.31
}Additional Features
🔐 Identity Resolution
We assign a lead_id and account_id on delivery. We provide a crosswalk table that links your native IDs to ours for seamless integration.
⚠️ Error Handling
Every delivery includes an errors file with row_number, field, value, and reason. Systemic errors are fixed in the next run.
🔄 Freshness & Cadence
Standard delivery is weekly. Daily available for API and Sheets. Real-time webhooks available for conversions.
🌏 International Support
We support Hangul and English names. Korean names include romanized versions. Addresses normalized with country-specific formats.
Retail Pilot Fields
Optional for Korean Brands Launching in U.S.
retailer_sku, case_pack, master_carton_qty, pallet_pattern, carton_dimensions_cm_lwh, carton_weight_kg, upc_gtin, msrp_usd, wholesale_usd, map_usd
Use this block if you plan a small pallet launch. Adding retail fields can extend the setup timeline by 4-8 weeks due to retailer onboarding.
Frequently Asked Questions
Can you match our internal IDs?
Yes. Provide a two-column crosswalk. We will persist it in all future files.
Can you push data straight into our warehouse?
Yes. BigQuery, Snowflake, Redshift, Postgres, or S3. We document the table schemas first.
Can you accept other formats?
Yes. Parquet or NDJSON are available by request.
Need a Custom Format?
Email henry@primechasedata.com with a sample file and your target system. We'll return a mapping and delivery plan.
Discuss Requirements