API ReferenceRewardsLocations

Get Eligible Locations

Retrieve national and local geographic locations data that a specified user has eligible in-store offers at. To include local merchant locations, include the `includeLocal` query parameter. Call this endpoint to build out your [targeted offers](https://github.com/kard-financial/kard-postman?tab=readme-ov-file#b-targeted-offers) and [map-specific UX experiences](https://github.com/kard-financial/kard-postman#c-discover-clos-near-you-map-view). Please note that Longitude and Latitude fields are prioritized over State, City and Zipcode.<br/> <b>Required scopes:</b> `rewards:read`

Path parameters

referringPartnerUserIdstringRequired
Referring partner user ID from issuer that specifies user

Headers

AuthorizationstringRequired

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

pageintegerOptional

Page number [>= 0], (default = 0)

limitintegerOptional

Maximum number of locations to be returned [1 - 200], (default = 200)

locationNameSortenumOptional

Sort location names (1 for A-Z, -1 for Z-A)

Allowed values:
citySortenumOptional

Sort city names (1 for A-Z, -1 for Z-A)

Allowed values:
stateSortenumOptional

Sort state names (1 for A-Z, -1 for Z-A)

Allowed values:
locationNamestringOptional
Name of location
citystringOptional

City of location; REQUIRES state query parameter

zipCodestringOptional

Zip Code of location; CANNOT provide State, City, Longitude, Latitude, or Radius query params when using zipCode

stateenumOptional

State of location; REQUIRES city field

googleIdstringOptional
GoogleId from location
sourceenumOptional
Source of the merchant associated to the location
Allowed values:
categoryenumOptional

Category of merchant associated with location. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)

longitudedoubleOptional

Longitude to search locations from [-180 - 180], REQUIRES latitude field

latitudedoubleOptional

Latitude to search locations from [-90 - 90], REQUIRES longitude field

radiusintegerOptional

Radius to search for locations in miles [1 - 50], (default = 10). REQUIRES longitude & latitude fields

includeLocalbooleanOptional
When included, the response will include local merchant locations alongside national merchant locations. If omitted, the response will only contain national merchant locations.
createdDateStartdatetimeOptional

Time in string format for location createdDate search start (UTC)

createdDateEnddatetimeOptional

Time in string format for location createdDate search end (UTC)

Response

This endpoint returns a list of objects.
_idstring
Location ID in Kard's system
addressobject
Address of location
categoryenum
Category of merchant associated with location
createdDatedatetime

Created date of location in Kard’s system (UTC)

geoLocationobject

Geo-coordinates of location

lastModifieddatetime

Last modified date of location in Kard’s system (UTC)

locationTypeenum
Type of offer associated to location, will always be in INSTORE
Allowed values:
merchantobject
Merchant object associated with location
merchantIdstring
Merchant ID in Kard's system associated to location
namestring
Name of the location
offerslist of objects
Offers associated to the location
phonestring
Phone number for location
sourceenum
Source of the merchant associated to the location
Allowed values:
googleIdstring or null
GoogleId of location
operationHoursobject or null
Hours of operation for location

Errors