PUBLIC CONTRACT REFERENCE / VERSION 1
Sports Picks API Field Dictionary
Every licensed API record uses the same normalized field contract. This public dictionary explains each field, its type, nullability, lifecycle role, and safe handling before a private integration.
Downloadable integration assets
Use the machine-readable schema to validate a record and the illustrative list response to plan an initial mapping. Sample values demonstrate structure only; they are not current picks, fixtures, prices, or performance claims.
Record fields
| Field | Type | Null | Meaning | Example |
|---|---|---|---|---|
id | string | Never | Opaque PowerHouse record identifier. Store this value and use it to reconcile later lifecycle updates. | ph_pick_… |
sport | string | Never | Normalized sport package associated with the record. | NBA |
league | string | Allowed | Competition or league when the licensed source record supplies one. | NBA |
roundOrWeek | string | Allowed | Canonical round, week, or stage label used consistently by schedule and pick-card surfaces. | NBA Finals · Game 4 |
eventMetadata | object | Allowed | Event metadata for presentation and grouping: the structured shared card-contract document where the licensed record carries one, otherwise the record's own metadata bag (round or week labels, presentation assets). Null when the record carries neither. | {"schema_version":"1.0","sport_key":"nba",…} |
eventDescription | string | Never | Human-readable event label suitable for operational review and editorial mapping. | Away Team at Home Team |
eventDate | ISO 8601 string | Never | Scheduled event time expressed as an ISO 8601 timestamp. | 2026-10-21T23:30:00.000Z |
homeTeam | string | Allowed | Normalized home participant for team sports. Null for formats where home and away do not apply. | Home Team |
awayTeam | string | Allowed | Normalized away participant for team sports. Null for formats where home and away do not apply. | Away Team |
marketType | string | Allowed | Normalized market family, such as moneyline, spread, total, or a supported player-prop market. | moneyline |
selection | string | Never | The exact qualified selection represented by this record. | Home Team |
line | number | Allowed | Market line when the selection depends on a spread, total, or threshold. | -3.5 |
odds | number | Allowed | Licensed decimal price when an eligible bookmaker value is available. | 1.91 |
oddsFormat | "decimal" | Allowed | Format of the odds value. It is decimal when odds are present and null when they are absent. | decimal |
bookmaker | string | Allowed | Bookmaker attribution attached to the supplied price when licensed and available. | Licensed bookmaker |
probability | number | Allowed | Model probability expressed on a 0–100 scale. It is not a guarantee of the event outcome. | 66.4 |
confidenceTier | string | Allowed | Licensed qualitative tier associated with the selection when supplied by the source workflow. | qualified |
reasoning | string | Allowed | Licensed publishing rationale. Availability can vary by product and field entitlement. | Illustrative publishing rationale. |
status | enum | Never | Current lifecycle state: upcoming, live, settled, or void. | upcoming |
result | enum | Allowed | Final result after settlement: win, loss, push, or void. Null before settlement. | null |
settledAt | ISO 8601 string | Allowed | Settlement timestamp when the record has been settled. Null before settlement. | null |
publishedAt | ISO 8601 string | Never | Timestamp at which the underlying record was published into the PowerHouse delivery contract. | 2026-10-21T15:00:00.000Z |
attribution | string | Allowed | Source attribution to display or preserve when required by the active licence. | Powered by PowerHouse |
widgetEventIdentity | object | Never | Composite widget event identity: the source event, the sport key and the competition key always travel together, so records for one event can be grouped without name matching. | {"sourceEventId":"…","sportKey":"nba","competitionKey":"nba"} |
homeIdentityKey | string | Allowed | Exact canonical key for the home participant. It is derived from the exact participant name and never from an approximate match. | home-team |
awayIdentityKey | string | Allowed | Exact canonical key for the away participant. | away-team |
subjectIdentityKey | string | Allowed | The one participant THIS pick is about, as an exact canonical key. Stated by the producer; never derived from the selection text. It is honoured only when it exactly equals this event's home or away participant key, and is null whenever the pick has no participant subject (a total, a yes/no market) or the producer stated none. | home-team |
homeLogoUrl | string | Allowed | Home participant logo URL when the licensed source record supplies one on an approved image host. | null |
awayLogoUrl | string | Allowed | Away participant logo URL when the licensed source record supplies one on an approved image host. | null |
homeNationality | string | Allowed | Home participant nationality where the sport uses one. | null |
awayNationality | string | Allowed | Away participant nationality where the sport uses one. | null |
isPlayerPick | boolean | Never | Whether the record is a player selection rather than a team selection. | false |
Illustrative list response
The list endpoint returns licensed records inside data, cursor state inside page, and a requestId for traceability.
{
"data": [
{
"id": "ph_pick_illustrative",
"sport": "NBA",
"league": "NBA",
"roundOrWeek": "NBA Finals · Game 4",
"eventDescription": "Away Team at Home Team",
"eventDate": "2026-10-21T23:30:00.000Z",
"homeTeam": "Home Team",
"awayTeam": "Away Team",
"marketType": "moneyline",
"selection": "Home Team",
"line": null,
"odds": 1.91,
"oddsFormat": "decimal",
"bookmaker": "Licensed bookmaker",
"probability": 66.4,
"confidenceTier": "qualified",
"reasoning": "Illustrative publishing rationale. Production wording depends on the licensed record.",
"status": "upcoming",
"result": null,
"settledAt": null,
"publishedAt": "2026-10-21T15:00:00.000Z",
"attribution": "Powered by PowerHouse",
"widgetEventIdentity": {
"sourceEventId": "derived:v1:7ab9554b5e9f978fd379709a2775dcec620ad1af325f018ad4bc9d73c614f92f",
"sportKey": "nba",
"competitionKey": "nba"
},
"eventMetadata": {
"schema_version": "1.0",
"source_event_id": "derived:v1:7ab9554b5e9f978fd379709a2775dcec620ad1af325f018ad4bc9d73c614f92f",
"sport_key": "nba",
"competition_key": "nba",
"competition_name": "NBA",
"competition_type": null,
"is_championship_event": false,
"championship_logo_key": null,
"logo_priority": "competition",
"stage_key": "unknown",
"stage_label": null,
"round_label": null,
"round_number": null,
"matchday_number": null,
"week_number": null,
"game_number": null,
"leg_number": null,
"total_legs": null,
"series_game_number": null,
"series_best_of": null,
"aggregate_home_score": null,
"aggregate_away_score": null,
"event_date": "2026-10-21T23:30:00.000Z",
"timezone": null,
"venue_name": null,
"venue_city": null,
"venue_country": null,
"home_participant": "Home Team",
"away_participant": "Away Team",
"display_context": {
"primary_label": "NBA",
"secondary_label": null,
"tertiary_label": null,
"short_event_code": null
},
"sport_context": {}
},
"homeIdentityKey": "home-team",
"awayIdentityKey": "away-team",
"subjectIdentityKey": "home-team",
"homeLogoUrl": null,
"awayLogoUrl": null,
"homeNationality": null,
"awayNationality": null,
"isPlayerPick": false
}
],
"page": {
"nextCursor": null,
"hasMore": false
},
"requestId": "req_illustrative"
}Nullability and entitlement
Required means the key is part of the normalized record contract; it does not mean its value can never be null. A nullable field can be unavailable because the sport format does not use it, the source record does not supply it, or the active licence does not include that enrichment.
Consumers should distinguish null from an empty string and should never infer a probability, line, price, bookmaker, result, or settlement timestamp when the API returns null.
Lifecycle invariants
- upcoming
- The qualified record is attached to a future event.
- live
- The event time has arrived and the event may be in progress.
- settled
- A final result is available as win, loss, push, or void.
- void
- The record is not eligible for normal publication or settlement.
Move from public contract to licensed integration
Review authentication, filters, pagination, errors, and endpoint behavior in the complete API documentation, then validate the fields against one real publishing surface.