Winners

Endpoints for querying prizes and draws.

List Winners

GET /api/awardeds

Returns a paginated list of winners with filtering options by date range and specific prizes. This endpoint provides access to loyalty program prizes and winning records with company and client information.

Use cases:

• Check promotion winners
• Export winners list
• Integrate with prize delivery system

Query Parameters

Parameter	Type	Required	Description
date_start	string	Yes	Start date to filter records (YYYY-MM-DD)
date_end	string	Yes	End date to filter records (YYYY-MM-DD)
limit	integer	Yes	Number of records per request
offset	integer	Yes	Number of records to skip (min 0)
awardeds_id	array	No	Specific prize IDs to filter (UUIDs)

Request Example

curl -X GET "https://api-b2s.experienciab2s.com/api/awardeds?date_start=2024-01-01&date_end=2024-12-31&limit=50&offset=0" \
     -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200)

{
  "total": 125,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "id": "abc123e4-56f7-89ab-cdef-123456789abc",
      "created_at": "2024-04-15T10:30:00.000Z",
      "awarded": {
        "id": "def456g7-89hi-01jk-lmno-456789012def",
        "name": "Monthly Premium Draw"
      },
      "client": {
        "id": "ghi789j0-12kl-34mn-opqr-789012345ghi",
        "name": "Maria Silva",
        "email": "maria.silva@example.com",
        "phone": "(11) 99999-9999",
        "born_date": "1985-03-15T00:00:00.000Z"
      },
      "company": {
        "id": "jkl012m3-45no-67pq-rstu-012345678jkl",
        "name": "Good Flavor Restaurant"
      }
    },
    {
      "id": "mno345p6-78qr-90st-uvwx-345678901mno",
      "created_at": "2024-04-14T14:20:00.000Z",
      "awarded": {
        "id": "pqr678s9-01tu-23vw-xyza-678901234pqr",
        "name": "Weekly Cashback"
      },
      "client": {
        "id": "stu901v2-34wx-56yz-abcd-901234567stu",
        "name": "John Santos",
        "email": "john.santos@example.com",
        "phone": null,
        "born_date": null
      },
      "company": {
        "id": "vwx234y5-67za-89bc-defg-234567890vwx",
        "name": "Tech Electronics Store"
      }
    }
  ]
}

Response Structure

Field	Type	Description
total	integer	Total available records
limit	integer	Limit per page
offset	integer	Current offset
data	array	List of winners

Winner Structure

Field	Type	Description
id	string	Unique record ID
created_at	string	Creation date
awarded.id	string	Prize ID
awarded.name	string	Prize name
client.id	string	Client ID
client.name	string	Client name
client.email	string	Client email
client.phone	string	Client phone
client.born_date	string	Birth date
company.id	string	Company ID
company.name	string	Company name

Response Codes

Code	Description
200	Winners found
403	Invalid token or unauthorized user
404	Integration token not found