Field-Level Query Guide

Complete guide for querying specific fields in each API endpoint.

← Back to Main README - Overview and features
← Quick Start Guide - Setup instructions
← API Documentation - Testing tools and Swagger
Testing Examples → - Practical code examples

Partners API - `/odata/Partners`

The authenticated partner can only access their own partner record. This endpoint always returns one record.

Available Fields

Id (long) - Partner ID
Name (string) - Partner name
Description (string) - Partner description (mapped from FooterCopyright)
LogoUrl (string) - Logo URL
WebsiteUrl (string) - Partner website / rewards URL
IsActive (bool) - True when Status is 'Active'
CategoryId (long) - Category ID (may be null)

Navigation Properties (use `$expand`)

RewardRewards - Rewards belonging to this partner (available via single-record endpoint)

Query Examples

Get Authenticated Partner

GET /odata/Partners

Get Partner by ID

GET /odata/Partners(123)

Select Specific Fields

GET /odata/Partners?$select=Id,Name,WebsiteUrl,IsActive

Rewards API - `/odata/Rewards`

Available Fields

Identity & Basic Info

Id (long) - Reward ID
Title (string) - Reward title
Name (string) - Reward name (same as Title)
SubTitleText (string) - Subtitle text
Description (string) - Offer description (same as OfferDescription)
OfferDescription (string) - Offer description
BrandName (string) - Brand name
BrandId (long) - Associated brand ID
PartnerId (long) - Associated partner ID
Status (string) - Status string (e.g., 'Active')
IsActive (bool) - True when Status is 'Active'

Discount Information

DiscountAmt (double) - Discount amount
DiscountCode (string) - Discount code
DiscountString (string) - Discount description

URLs & Links

BrowseUrl (string) - Browse URL
RewardUrl (string) - Reward claim URL
RewardUrlInstruction (string) - Instructions for reward URL
MoreInfoUrl (string) - More information URL

Status & Features

IsFeatured (bool) - Is featured
IsHotOffer (bool) - Is hot offer
PartnerHighlighted (bool) - Is highlighted by partner
UseOneTimeRewardCodes (bool) - Uses one-time codes
UseOneTimeQrRewardCodes (bool) - Uses one-time QR codes
ViewCount (int) - Number of views
SortOrder (int) - Display sort order

Availability

LocationAll (bool) - Available in all locations
LocationsList (string) - Comma-separated location list
MemberLevelList (string) - Comma-separated member level list
MinAvailLevel (string) - Minimum availability level
ValidFrom (DateTime) - Start date
ValidUntil (DateTime) - End date
DateAdded (DateTime) - Date reward was added
CreatedAt (DateTime) - Same as DateAdded

Content

HowToClaim (string) - Claim instructions
RewardTerms (string) - Terms and conditions

Navigation Properties (use `$expand`)

RewardRewardOrgUnit - Organisation units associated with the reward
RewardMemberlevels - Member levels eligible for the reward
RewardLocations - Locations where the reward is available
RewardRewardDiscountCountrys - Countries where discount is valid
RewardBrand - Brand details
RewardPartner - Partner details

Query Examples

Search by Title

GET /odata/Rewards?$filter=contains(Title,'Discount')

Get Active Rewards Only

GET /odata/Rewards?$filter=IsActive eq true

Get Featured Rewards

GET /odata/Rewards?$filter=IsFeatured eq true&$orderby=Title

Get Hot Offers

GET /odata/Rewards?$filter=IsHotOffer eq true

Filter by Partner

GET /odata/Rewards?$filter=PartnerId eq 123

Get Rewards with Discount Code

GET /odata/Rewards?$filter=DiscountCode ne null

Get Rewards by Discount Amount Range

GET /odata/Rewards?$filter=DiscountAmt ge 10 and DiscountAmt le 50

Select Specific Fields

GET /odata/Rewards?$select=Id,Title,DiscountString,IsActive,IsFeatured

Expand Brand and Partner

GET /odata/Rewards?$expand=RewardBrand,RewardPartner

Expand Member Levels and Locations

GET /odata/Rewards?$expand=RewardMemberlevels,RewardLocations

Complex Query - Active Featured Rewards

GET /odata/Rewards?$filter=IsActive eq true and IsFeatured eq true&$orderby=Title&$select=Id,Title,DiscountString

Get Rewards Valid in a Date Range

GET /odata/Rewards?$filter=ValidFrom le 2024-12-31T00:00:00Z and ValidUntil ge 2024-01-01T00:00:00Z

Tracking Activities API - `/odata/TrackingActivities`

Backed by Elasticsearch. All data is automatically scoped to the authenticated partner. Deep pagination (beyond 10,000 records) uses search_after tokens automatically via @odata.nextLink.

Available Fields

Id (long) - Activity ID
CreatedAt (DateTime) - Activity timestamp
Type (string) - Activity type (e.g., 'click', 'view', 'impression')
UserId (long) - User ID
RewardId (long) - Reward ID

Navigation Properties (use `$expand`)

User - User who performed the activity (from Elasticsearch)
Reward - Reward associated with the activity

Supported `$filter` Fields

The Elasticsearch backend supports filtering on: CreatedAt (gt/ge/lt/le), UserId (eq), RewardId (eq), Type (eq)

Supported `$orderby` Fields

CreatedAt (default, descending), UserId, RewardId, Type

Query Examples

Get Activities by Type

GET /odata/TrackingActivities?$filter=Type eq 'click'

Get Activities for Specific User

GET /odata/TrackingActivities?$filter=UserId eq 456

Get Activities for Specific Reward

GET /odata/TrackingActivities?$filter=RewardId eq 789

Get Activities by Date Range

GET /odata/TrackingActivities?$filter=CreatedAt ge 2024-01-01T00:00:00Z and CreatedAt le 2024-01-31T23:59:59Z

Get Recent Activities (Last 24 Hours)

GET /odata/TrackingActivities?$filter=CreatedAt ge 2024-11-04T00:00:00Z&$orderby=CreatedAt desc

Expand User and Reward Data

GET /odata/TrackingActivities?$expand=User,Reward&$top=100

Complex Query - User Activity for a Specific Reward Type

GET /odata/TrackingActivities?$filter=UserId eq 456 and Type eq 'click'&$orderby=CreatedAt desc&$top=100

Get Multiple Activity Types

GET /odata/TrackingActivities?$filter=Type eq 'click' or Type eq 'view'

Tracking Logins API - `/odata/TrackingLogins`

Backed by Elasticsearch. All data is automatically scoped to the authenticated partner. Deep pagination (beyond 10,000 records) uses search_after tokens automatically via @odata.nextLink.

Available Fields

Id (long) - Login ID
LoginTime (DateTime) - Login timestamp
UserId (long) - User ID
CachedAt (DateTime) - Timestamp when this record was fetched

Navigation Properties (use `$expand`)

User - User who logged in (from Elasticsearch)

Supported `$filter` Fields

The Elasticsearch backend supports filtering on: LoginTime (gt/ge/lt/le), UserId (eq)

Supported `$orderby` Fields

LoginTime (default, descending), UserId

Query Examples

Get Logins for Specific User

GET /odata/TrackingLogins?$filter=UserId eq 456

Get Logins by Date Range

GET /odata/TrackingLogins?$filter=LoginTime ge 2024-01-01T00:00:00Z and LoginTime le 2024-01-31T23:59:59Z

Get Recent Logins (Last 7 Days)

GET /odata/TrackingLogins?$filter=LoginTime ge 2024-10-29T00:00:00Z&$orderby=LoginTime desc

Expand User Data

GET /odata/TrackingLogins?$filter=UserId eq 456&$expand=User

GET /odata/TrackingLogins?$filter=UserId eq 456&$orderby=LoginTime desc&$top=1

Tracking Impressions API - `/odata/TrackingImpressions`

Backed by the database. Data is cached for 30 minutes — check the CachedAt field for cache age. All records are automatically scoped to the authenticated partner. Standard $skip/$top pagination applies.

Available Fields

Id (int) - Impression ID
UserId (string) - User ID (stored as string)
RewardId (long) - Reward ID
CreatedAt (DateTime) - Impression timestamp
CachedAt (DateTime) - Timestamp when this record was cached

Navigation Properties (use `$expand`)

User - User who viewed the reward
Reward - Reward that was viewed
User($expand=AccountsUsersOrgUnits) - Include user's organisation units

Query Examples

Get Impressions for Reward

GET /odata/TrackingImpressions?$filter=RewardId eq 789

Get Impressions with User and Reward Details

GET /odata/TrackingImpressions?$expand=User,Reward&$select=Id,CreatedAt

Get Impressions with User and Org Units

GET /odata/TrackingImpressions?$expand=User($expand=AccountsUsersOrgUnits)

Date Range Query

GET /odata/TrackingImpressions?$filter=CreatedAt ge 2024-01-01T00:00:00Z&$orderby=CreatedAt desc

Users API - `/odata/Users`

Backed by the database. All records are automatically scoped to the authenticated partner. OData $filter, $orderby, $select, $top, and $skip are all supported.

Available Fields

Identity

Id (long) - User ID
Email (string) - Email address

Personal Info

FirstName (string) - First name
LastName (string) - Last name

Account Status

IsActive (bool) - Is active
Status (string) - Account status string (e.g., 'active')
DateJoined (DateTime) - Date the member joined
RenewalDate (DateTime) - Renewal date
DateRenewed (DateTime) - Date last renewed
DateCancelled (DateTime) - Date cancelled (if applicable)
MemberLevel (string) - Member tier or level

Relationships

PartnerId (long) - Partner ID (automatically scoped)
CountryName (string) - Country name

Navigation Properties (use `$expand`)

AccountsUsersOrgUnits - Organisation units the user belongs to
AccountsUsersOrgUnits($expand=OrgUnit) - Include org unit details

Cache Metadata

CachedAt (DateTime) - Time data was cached

Query Examples

Search by Email

GET /odata/Users?$filter=Email eq 'user@example.com'

Get Active Users Only

GET /odata/Users?$filter=IsActive eq true

Get Recently Joined Users

GET /odata/Users?$filter=DateJoined ge 2024-01-01T00:00:00Z&$orderby=DateJoined desc

Search by Name

GET /odata/Users?$filter=contains(FirstName,'John') or contains(LastName,'Smith')

Filter by Member Level

GET /odata/Users?$filter=MemberLevel eq 'Gold'

Filter by Status

GET /odata/Users?$filter=Status eq 'active'

Select Specific Fields

GET /odata/Users?$select=Id,Email,FirstName,LastName,IsActive,DateJoined

Expand Org Units

GET /odata/Users?$expand=AccountsUsersOrgUnits

Expand Org Units with Details

GET /odata/Users?$expand=AccountsUsersOrgUnits($expand=OrgUnit)

Users Elastic API - `/odata/UsersElastic`

Backed by Elasticsearch. Returns users who have logged in at least once. Deep pagination uses a searchAfter query parameter (a numeric user ID) when $skip >= 10000.

Available Fields

Fields returned are from the Elasticsearch user-login index and may vary. Common fields include:

Id (long) - User ID
Email (string) - Email address
FirstName (string) - First name
LastName (string) - Last name
DateJoined (DateTime) - Date joined

Supported `$filter` Fields

DateJoined (le) - Filter users who joined on or before this date

Query Examples

GET /odata/UsersElastic

Filter by Join Date

GET /odata/UsersElastic?$filter=DateJoined le 2024-01-01T00:00:00Z

Paginated with Custom Page Size

GET /odata/UsersElastic?$top=10000&$skip=0

User Analytics REST Endpoints

User Counts - `GET /api/users/counts`

Returns aggregated counts for churn metrics.

Query Parameters:

joinedBefore (DateTime, optional) - Only include users who joined on or before this date
joinedAfter (DateTime, optional) - Only include users who joined on or after this date

Response Fields:

TotalUsers (int) - Total number of users
ActiveUsers (int) - Users who are active, not cancelled, and not expired
ChurnedUsers (int) - Total minus active
RenewedUsers (int) - Users who have a DateRenewed value
CancelledUsers (int) - Users who have a DateCancelled value
ExpiredUsers (int) - Users with expired renewal who have not renewed
AtRiskUsers (int) - Always 0; calculated separately based on login activity

Examples:

GET /api/users/counts
GET /api/users/counts?joinedAfter=2024-01-01&joinedBefore=2024-12-31

User Cohorts - `GET /api/users/cohorts`

Returns cohort retention data grouped by the month users joined (last 24 months).

Response Fields (per cohort):

CohortMonth (string) - Month in YYYY-MM format
InitialUsers (int) - Number of users who joined in this month
RemainingUsers (int) - Currently active users from this cohort
ChurnedUsers (int) - InitialUsers minus RemainingUsers
RetentionRate (double) - Fraction of original cohort still active (0–1)
ChurnRate (double) - Fraction of original cohort who churned (0–1)

Example:

GET /api/users/cohorts

User Segments - `GET /api/users/segments`

Returns churn rates segmented by country and member level (top 5 of each).

Response Fields (per segment):

Segment (string) - Segment name (country name or member level)
Category (string) - 'Country' or 'MemberLevel'
TotalUsers (int) - Total users in this segment
HighRiskCount (int) - Users whose renewal is expiring within 30 days
ChurnRate (double) - Fraction of segment that is churned (0–1)

Example:

GET /api/users/segments

Reward Countries API - `/odata/RewardCountries`

Available Fields

Id (long) - Country ID
Name (string) - Country name
Code (string) - Country code
CreatedAt (DateTime) - Creation timestamp
UpdatedAt (DateTime) - Last updated timestamp

Query Examples

Get Country by Code

GET /odata/RewardCountries?$filter=Code eq 'UK'

Search by Name

GET /odata/RewardCountries?$filter=contains(Name,'United')

Order by Name

GET /odata/RewardCountries?$orderby=Name asc

Reward Brands API - `/odata/RewardBrands`

Brands are filtered by the authenticated partner. Data is cached for 30 minutes.

Available Fields

Id (long) - Brand ID
Name (string) - Brand name
ContactName (string) - Contact person name
LogoUrl (string) - Logo URL
ContactEmail (string) - Contact email address
Status (string) - Status (e.g., 'Active')

Query Examples

Search by Brand Name

GET /odata/RewardBrands?$filter=contains(Name,'Nike')

Get Brand by Status

GET /odata/RewardBrands?$filter=Status eq 'Active'

Select Key Fields

GET /odata/RewardBrands?$select=Id,Name,ContactName,LogoUrl,ContactEmail,Status

Order by Name

GET /odata/RewardBrands?$orderby=Name asc

Partner Categories API - `/odata/PartnerCategories`

Categories are filtered by the authenticated partner. Data is cached for 30 minutes.

Available Fields

Id (long) - Category ID
Name (string) - Category name
Description (string) - Category description (same value as Name)
CategoryAlias (string) - Category alias
CategoryImageUrl (string) - Category image URL
ShowCategory (bool) - Whether category is visible
SortOrder (int) - Display sort order

Query Examples

Search by Name

GET /odata/PartnerCategories?$filter=contains(Name,'Fitness')

Get Visible Categories Only

GET /odata/PartnerCategories?$filter=ShowCategory eq true

Select Key Fields

GET /odata/PartnerCategories?$select=Id,Name,Description,CategoryAlias,CategoryImageUrl,ShowCategory,SortOrder

Order by Sort Order

GET /odata/PartnerCategories?$orderby=SortOrder asc

Common Query Patterns

Pagination

# Get first 20 items
GET /odata/Partners?$top=20

# Get items 21-40
GET /odata/Partners?$top=20&$skip=20

Sorting

# Ascending
GET /odata/Rewards?$orderby=Title asc

# Descending
GET /odata/TrackingActivities?$orderby=CreatedAt desc

# Multiple fields
GET /odata/Users?$orderby=LastName asc,FirstName asc

Field Selection

# Select specific fields
GET /odata/Partners?$select=Id,Name,WebsiteUrl

# Select with filter
GET /odata/Rewards?$filter=IsActive eq true&$select=Id,Title,DiscountString

Counting

# Get total count
GET /odata/TrackingActivities/$count

# Get count with filter
GET /odata/Users/$count?$filter=IsActive eq true

String Functions

# Contains (case-sensitive)
GET /odata/Partners?$filter=contains(Name,'Gym')

# Contains (case-insensitive)
GET /odata/Partners?$filter=contains(tolower(Name),'gym')

# Starts with
GET /odata/Rewards?$filter=startswith(Title,'Gold')

# Ends with
GET /odata/Users?$filter=endswith(Email,'@example.com')

Date Queries

# Greater than
GET /odata/TrackingActivities?$filter=CreatedAt gt 2024-01-01T00:00:00Z

# Date range
GET /odata/TrackingLogins?$filter=LoginTime ge 2024-01-01T00:00:00Z and LoginTime le 2024-01-31T23:59:59Z

# Today's data (example)
GET /odata/TrackingActivities?$filter=CreatedAt ge 2024-11-05T00:00:00Z

Null Checks

# Is null
GET /odata/Rewards?$filter=DiscountCode eq null

# Is not null
GET /odata/Rewards?$filter=DiscountCode ne null

Combining Filters

# AND
GET /odata/Rewards?$filter=IsActive eq true and IsFeatured eq true

# OR
GET /odata/TrackingActivities?$filter=Type eq 'click' or Type eq 'view'

# Complex
GET /odata/Users?$filter=(IsActive eq true and IsStaff eq false) or IsSuperuser eq true

Tips for Effective Querying

Always use $select when you don't need all fields - it improves performance
Use $top to limit results and prevent large data transfers
Add $orderby for consistent pagination
Use $count to get totals without retrieving all data
Combine filters to narrow down results efficiently
Use tolower() for case-insensitive string searches
Test queries in Swagger before implementing in code
Check $metadata endpoint for exact field names and types

Getting Field Information

View All Available Fields

Navigate to the OData metadata endpoint:

GET https://reporting.api.myezrewards.com/odata/$metadata

This returns the complete schema with all entity types and their properties.

Use Swagger UI

Navigate to https://reporting.api.myezrewards.com/swagger
Expand any endpoint
View the schema section for available fields
Try queries interactively

← Back to Main README - Overview and features
← Quick Start Guide - Setup instructions
← API Documentation - Testing tools
Testing Examples → - PowerShell, curl, and C# code samples

Field-Level Query Guide

📚 Documentation Navigation

Partners API - /odata/Partners

Available Fields

Navigation Properties (use $expand)

Query Examples

Get Authenticated Partner

Get Partner by ID

Select Specific Fields

Rewards API - /odata/Rewards

Available Fields

Identity & Basic Info

Discount Information

URLs & Links

Status & Features

Availability

Content

Navigation Properties (use $expand)

Query Examples

Search by Title

Get Active Rewards Only

Get Featured Rewards

Get Hot Offers

Filter by Partner

Get Rewards with Discount Code

Get Rewards by Discount Amount Range

Select Specific Fields

Expand Brand and Partner

Expand Member Levels and Locations

Complex Query - Active Featured Rewards

Get Rewards Valid in a Date Range

Tracking Activities API - /odata/TrackingActivities

Available Fields

Navigation Properties (use $expand)

Supported $filter Fields

Supported $orderby Fields

Query Examples

Get Activities by Type

Get Activities for Specific User

Get Activities for Specific Reward

Get Activities by Date Range

Get Recent Activities (Last 24 Hours)

Expand User and Reward Data

Complex Query - User Activity for a Specific Reward Type

Get Multiple Activity Types

Tracking Logins API - /odata/TrackingLogins

Available Fields

Navigation Properties (use $expand)

Supported $filter Fields

Supported $orderby Fields

Query Examples

Get Logins for Specific User

Get Logins by Date Range

Get Recent Logins (Last 7 Days)

Expand User Data

Get Latest Login for a User

Tracking Impressions API - /odata/TrackingImpressions

Available Fields

Navigation Properties (use $expand)

Query Examples

Get Impressions for Reward

Get Impressions with User and Reward Details

Get Impressions with User and Org Units

Date Range Query

Users API - /odata/Users

Available Fields

Identity

Personal Info

Account Status

Relationships

Navigation Properties (use $expand)

Cache Metadata

Query Examples

Search by Email

Get Active Users Only

Get Recently Joined Users

Search by Name

Filter by Member Level

Filter by Status

Select Specific Fields

Partners API - `/odata/Partners`

Navigation Properties (use `$expand`)

Rewards API - `/odata/Rewards`

Navigation Properties (use `$expand`)

Tracking Activities API - `/odata/TrackingActivities`

Navigation Properties (use `$expand`)

Supported `$filter` Fields

Supported `$orderby` Fields

Tracking Logins API - `/odata/TrackingLogins`

Navigation Properties (use `$expand`)

Supported `$filter` Fields

Supported `$orderby` Fields

Tracking Impressions API - `/odata/TrackingImpressions`

Navigation Properties (use `$expand`)

Users API - `/odata/Users`

Navigation Properties (use `$expand`)

Users Elastic API - `/odata/UsersElastic`

Supported `$filter` Fields

User Counts - `GET /api/users/counts`

User Cohorts - `GET /api/users/cohorts`

User Segments - `GET /api/users/segments`

Reward Countries API - `/odata/RewardCountries`

Reward Brands API - `/odata/RewardBrands`

Partner Categories API - `/odata/PartnerCategories`