Prizes
/
Record Prize

Record Prize

POST
https://api.vivamo.co/v1/customers/{externalCustomerId}/prizes

Record a W-2G prize for a customer. The prize is validated against IRS filing thresholds based on your operator's personal tax type: Bingo prizes must be at least $1,200 and include a ticket or card number; Horse Racing prizes must exceed $600 and be at least 300 times the wager amount, with a race name. Returns the prize record and, if the customer has not yet completed a W-9, a w9CaptureUrl for tax form collection. Only available to operators with a bingo or horse_racing personal tax type.

Path parameters

    externalCustomerId
    string
    Required
    The customer identifier you provided when creating the record.

Request body

    reportableWinnings
    number
    Required
    IRS Box 1: gross winnings amount. Must meet the threshold for your tax type ($1,200 for bingo, $600 for horse racing).
    Examples:1500
    dateWon
    string
    Required
    IRS Box 2: date the prize was won (ISO 8601 format).
    Examples:2026-02-15
    typeOfWager
    string
    Required

    IRS Box 3: type of wager. Must be bingo for bingo operators.

    Examples:bingo
    federalIncomeTaxWithheld
    number
    Defaults: 0

    IRS Box 4: federal income tax withheld. Defaults to 0.

    race
    string
    IRS Box 6: race name. Required for horse racing operators.
    winningsFromIdenticalWagers
    number
    IRS Box 7: winnings from identical wagers.
    wagerAmount
    number
    Wager amount. Required for horse racing operators — winnings must be at least 300 times this value.
    ticketOrCardNumber
    string
    IRS Box 5: ticket or card number. Required for bingo operators.
    Examples:TICKET-001
    payerInitials
    string
    IRS Box 8: initials of the first person to initiate the payout.
    payerLocation
    string
    IRS Box 10: window or location where the payout was made.
    cashierOrWindow
    string
    Cashier or window identifier.

Response

Prize recorded.
    message
    string
    Examples:Prize recorded successfully
    prizeRecord
    object
    A W-2G prize record for a customer.
      personalTaxType
      string
      The operator's personal tax type.
        bingo
        string
        horse_racing
        string
      taxYear
      integer

      Tax year derived from the dateWon field.

      Examples:2026
      status
      string
      Current filing status of the prize record.
      Examples:recorded
        recorded
        string
        submitted
        string
        filed
        string
      reportableWinnings
      number
      IRS Box 1: gross winnings amount.
      Examples:1500
      dateWon
      string
      IRS Box 2: date the prize was won.
      Examples:2026-02-15T00:00:00.000Z
      typeOfWager
      string

      IRS Box 3: type of wager (e.g. bingo, horse_racing).

      Examples:bingo
      federalIncomeTaxWithheld
      number

      IRS Box 4: federal income tax withheld. Defaults to 0.

      race
      string
      IRS Box 6: race name. Required for horse racing prizes.
      winningsFromIdenticalWagers
      number
      IRS Box 7: winnings from identical wagers.
      wagerAmount
      number
      Wager amount. Used for the 300x multiplier validation on horse racing prizes.
      ticketOrCardNumber
      string
      IRS Box 5: ticket or card number. Required for bingo prizes.
      Examples:TICKET-001
      payerInitials
      string
      IRS Box 8: first person to initiate the payout.
      payerLocation
      string
      IRS Box 10: window or location where the payout was made.
      cashierOrWindow
      string
      Cashier or window identifier.
      createdAt
      string
      Timestamp when the prize record was created.
    w9CaptureUrl
    string
    URL for the customer to complete their W-9 form. Only present when the customer has not yet submitted a W-9 for this operator.
Built with