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.

Open the JSON Schema Open an example response

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.	`basketball`
`league`	string	Allowed	Competition or league when the licensed source record supplies one.	`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`

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": "basketball",
      "league": "NBA",
      "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"
    }
  ],
  "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.

Read the API documentation Review API delivery Scope a pilot