For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
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. When none of the `locationNameSort`, `citySort` and `stateSort` query parameters are provided, locations are returned newest first (descending `createdDate`); if `latitude` and `longitude` are provided, locations are ordered by ascending distance from that point first, then newest first.<br/>
<b>Required scopes:</b> `rewards:read`
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
referringPartnerUserIdstringRequired
Referring partner user ID from issuer that specifies user
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)
supportedComponentsenumOptional
UI component types to include in included offers.
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
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
googleIdstringOptional
GoogleId of location
operationHoursobjectOptional
Hours of operation for location
Errors
400
Invalid Request
401
Unauthorized Error
404
Does Not Exist Error
500
Internal Server Error
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 and map-specific UX experiences. Please note that Longitude and Latitude fields are prioritized over State, City and Zipcode. When none of the locationNameSort, citySort and stateSort query parameters are provided, locations are returned newest first (descending createdDate); if latitude and longitude are provided, locations are ordered by ascending distance from that point first, then newest first. Required scopes:rewards:read
