Schema Reference

Complete type definitions for all API data models. These schemas reflect the exact structure returned by the API.

Device

Represents a device model in the registry. Contains metadata, specifications, and variant list.

Field	Type	Required	Description	Example
id	string	✓	Unique device identifier	"apple-iphone-14-pro"
name	string	✓	Display name of the device	"Apple iPhone 14 Pro"
slug	string	✓	URL-friendly identifier	"apple-iphone-14-pro"
category	object	✓	Device category information	{ name: "Smartphones", thumbnail: "..." }
make	object	✓	Manufacturer information	{ name: "Apple", thumbnail: "..." }
model_numbers	string[]	✓	Official model numbers	["A2650", "A2889"]
technical_specifications	object	✓	Key-value pairs of technical specs	{ "Display": "6.1 inch", "Processor": "A16 Bionic" }
release_date	string	✓	ISO 8601 release date	"2022-09-16"
thumbnail	string	✓	Device image URL	"https://cdn.souratlas.io/..."
status	string	✓	Device status	"active" or "discontinued"
model_identifiers	string[]	✓	Additional model identifiers	["iPhone15,2"]
variants	Variant[]	✓	Array of device variants	See Variant schema

Variant

Represents a specific SKU/configuration of a device (e.g., 128GB Space Black).

Field	Type	Required	Description	Example
id	string	✓	Unique variant identifier	"var_abc123"
sku	string	✓	Internal SKU code	"MPXV3LL/A"
price	number	✓	MSRP in cents	99900
name	string	✓	Variant display name	"128GB Space Black"
part_numbers	string[]	✓	Manufacturer part numbers	["MPXV3LL/A"]
model_numbers	string[]	✓	Model numbers for this variant	["A2650"]
thumbnail	string \| null	✓	Variant-specific image URL	"https://cdn.souratlas.io/..." or null
attributes	VariantAttribute[]	✓	Variant attributes (storage, color, etc.)	[{ attribute_name: "Storage", attribute_value: "128GB" }]
disabled	boolean	✓	Whether variant is disabled	false

VariantPricing

Pricing intelligence for a specific variant including buyback, resale, and market data.

Field	Type	Required	Description	Example
variant_id	string	✓	Variant identifier	"var_abc123"
device_name	string	✓	Parent device name	"Apple iPhone 14 Pro"
variant_name	string	✓	Variant name	"128GB Space Black"
buyback	object	✓	Buyback/trade-in pricing data	See nested structure below
buyback.current	ConditionPricing	✓	Current buyback prices by condition	{ Excellent: 65000, Good: 55000, Fair: 45000, Poor: 30000 }
buyback.historical	PricePoint[]	✓	Historical price data	[{ date: "2024-01-15", value: 65000, currency: "USD" }]
buyback.last_updated	string	✓	ISO 8601 timestamp	"2024-01-15T10:30:00Z"
buyback.source	string	✓	Data source	"internal" \| "external" \| "aggregated"
resale	object	✓	Resale/market value pricing data	See nested structure below
resale.current	ConditionPricing	✓	Current resale prices by condition	{ Excellent: 85000, Good: 75000, Fair: 60000, Poor: 45000 }
resale.historical	PricePoint[]	✓	Historical price data	[{ date: "2024-01-15", value: 85000, currency: "USD" }]
resale.trend	string	✓	Price trend direction	"rising" \| "stable" \| "falling"
resale.liquidity_score	number	✓	Market liquidity (1-100)	85
resale.last_updated	string	✓	ISO 8601 timestamp	"2024-01-15T10:30:00Z"
resale.source	string	✓	Data source	"internal" \| "external" \| "aggregated"
market_confidence	number	✓	Data confidence score (1-100)	92
data_points	number	✓	Number of data points used	1247
currency	string	✓	ISO 4217 currency code	"USD"

IMEILookupResult

Result of an IMEI/serial number risk assessment lookup.

Field	Type	Required	Description	Example
lookup_id	string	✓	Unique lookup identifier	"lookup_xyz789"
identifier	string	✓	The IMEI/serial queried	"358742012345678"
identifier_type	string	✓	Type of identifier	"imei" \| "serial" \| "esn"
timestamp	string	✓	ISO 8601 lookup timestamp	"2024-01-15T10:30:00Z"
device_match	object	✓	Device identification results	See nested structure below
device_match.confidence	number	✓	Match confidence (0-100)	95
device_match.matched_device_id	string \| undefined	—	Matched device ID	"apple-iphone-14-pro"
device_match.matched_device_name	string \| undefined	—	Matched device name	"Apple iPhone 14 Pro"
device_match.matched_variant_id	string \| undefined	—	Matched variant ID	"var_abc123"
device_match.matched_variant_name	string \| undefined	—	Matched variant name	"128GB Space Black"
blacklist_status	string	✓	Blacklist status	"clean" \| "blacklisted" \| "lost_stolen" \| "unknown"
carrier_lock	string	✓	Carrier lock status	"unlocked" \| "locked" \| "unknown"
carrier_name	string \| undefined	—	Carrier name if locked	"T-Mobile US"
risk_score	number	✓	Overall risk score (0-100)	15
risk_level	string	✓	Risk classification	"low" \| "medium" \| "high" \| "critical"
gsma_status	string \| undefined	—	GSMA database status	"clean"
ctia_status	string \| undefined	—	CTIA database status	"clean"
reported_lost_stolen	boolean	✓	Lost/stolen report flag	false
activation_lock	boolean \| undefined	—	Activation lock status	false
source	string	✓	Data source	"sickw" \| "internal" \| "mock"
freshness	string	✓	Data freshness	"real-time" \| "cached" \| "stale"
cache_age_minutes	number \| undefined	—	Cache age in minutes	5

DeviceRepairIntelligence

Repair intelligence data including repairability scores, common repairs, and cost estimates.

Field	Type	Required	Description	Example
device_id	string	✓	Device identifier	"apple-iphone-14-pro"
device_name	string	✓	Device name	"Apple iPhone 14 Pro"
variant_id	string \| undefined	—	Variant identifier if applicable	"var_abc123"
ifixit_score	number \| null	✓	iFixit repairability score (0-10), null if unavailable	6
repairability_rating	string	✓	Qualitative rating	"Excellent" \| "Good" \| "Fair" \| "Poor" \| "Very Poor" \| "Not Available"
common_repairs	CommonRepair[]	✓	List of common repairs	See CommonRepair schema
common_failure_points	string[]	✓	Known failure points	["Battery degradation", "Screen cracks"]
average_repair_cost	object \| null	✓	Average repair cost range, null if unavailable	{ min: 5000, max: 35000, currency: "USD" }
repair_roi_indicator	string	✓	ROI classification	"High" \| "Medium" \| "Low" \| "Unknown"
technical_notes	string[]	✓	Technical repair notes	["Requires heat gun for adhesive removal"]
proprietary_parts	string[]	✓	Proprietary parts list	["Pentalobe screws", "Tri-point screws"]
special_tools_required	string[]	✓	Required special tools	["Suction cup", "Spudger", "Pentalobe screwdriver"]
last_updated	string	✓	ISO 8601 timestamp	"2024-01-15T10:30:00Z"
source	string	✓	Data source	"ifixit" \| "internal" \| "aggregated" \| "mock"
data_completeness	number	✓	Data completeness score (0-100)	85

CommonRepair

Details about a common repair procedure.

Field	Type	Required	Description	Example
name	string	✓	Repair name	"Battery Replacement"
difficulty	string	✓	Repair difficulty	"Easy" \| "Moderate" \| "Difficult" \| "Very Difficult"
estimated_time_minutes	number	✓	Estimated repair time	45
parts	RepairPart[]	✓	Required parts	See RepairPart schema
ifixit_guide_url	string \| undefined	—	iFixit guide URL	"https://www.ifixit.com/Guide/..."

RepairPart

Information about a repair part.

Field	Type	Required	Description	Example
name	string	✓	Part name	"Battery"
cost_min	number	✓	Minimum cost in cents	2500
cost_max	number	✓	Maximum cost in cents	5000
currency	string	✓	ISO 4217 currency code	"USD"
availability	string	✓	Part availability	"available" \| "limited" \| "unavailable" \| "unknown"

UsageEvent

API usage tracking event for analytics.

Field	Type	Required	Description	Example
date	string	✓	ISO 8601 date	"2024-01-15"
api_requests	number	✓	Total API requests	1247
pricing_queries	number	✓	Pricing endpoint requests	342
imei_lookups	number	✓	IMEI lookup requests	89
repair_queries	number	✓	Repair endpoint requests	156
errors	number	✓	Error responses	12