For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Logo
Get supportSee a Demo
HomeAPI ReferenceSDKs
HomeAPI ReferenceSDKs
    • SDKs
    • WebView
  • API Reference
      • GETGet Offers By User
      • GETGet Locations By User
Get supportSee a Demo
API ReferenceRewards

Get Locations By User

GET
/v2/issuers/:organizationId/users/:userId/locations
GET
/v2/issuers/:organizationId/users/:userId/locations
$curl -G https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations \
>     -H "Authorization: Bearer <token>" \
>     -d "page[size]=1" \
>     -d "filter[latitude]=39.9419429" \
>     -d "filter[longitude]=-75.1446869" \
>     -d "filter[radius]=10" \
>     --data-urlencode include=offers,categories
1{
2  "data": [
3    {
4      "type": "location",
5      "id": "5e27318c9b346f00087fba8l",
6      "attributes": {
7        "name": "Worlds Greatest Chicken",
8        "address": {
9          "street": "120 Main St",
10          "city": "Philadelphia",
11          "state": "PA",
12          "zipCode": "19147"
13        },
14        "coordinates": {
15          "longitude": -75.1446869,
16          "latitude": 39.9419429
17        },
18        "phone": "+1 (123) 555-8880",
19        "operationHours": {
20          "periods": [
21            {
22              "close": {
23                "day": 1,
24                "time": "1700"
25              },
26              "open": {
27                "day": 1,
28                "time": "0900"
29              }
30            },
31            {
32              "close": {
33                "day": 2,
34                "time": "1700"
35              },
36              "open": {
37                "day": 2,
38                "time": "0900"
39              }
40            },
41            {
42              "close": {
43                "day": 3,
44                "time": "1700"
45              },
46              "open": {
47                "day": 3,
48                "time": "0900"
49              }
50            },
51            {
52              "close": {
53                "day": 4,
54                "time": "1700"
55              },
56              "open": {
57                "day": 4,
58                "time": "0900"
59              }
60            },
61            {
62              "close": {
63                "day": 5,
64                "time": "1700"
65              },
66              "open": {
67                "day": 5,
68                "time": "0900"
69              }
70            }
71          ],
72          "weekdayText": [
73            "Monday: 9:00 AM – 5:00 PM",
74            "Tuesday: 9:00 AM – 5:00 PM",
75            "Wednesday: 9:00 AM – 5:00 PM",
76            "Thursday: 9:00 AM – 5:00 PM",
77            "Friday: 9:00 AM – 5:00 PM",
78            "Saturday: Closed",
79            "Sunday: Closed"
80          ]
81        },
82        "partnerIds": [
83          {
84            "type": "google",
85            "id": "3pafnweri4"
86          }
87        ]
88      },
89      "relationships": {
90        "category": {
91          "data": [
92            {
93              "type": "category",
94              "id": "65920081b524d126068de24a"
95            }
96          ]
97        },
98        "offers": {
99          "data": [
100            {
101              "type": "standardOffer",
102              "id": "5e27318c9b346f00087fbb5b"
103            }
104          ]
105        }
106      }
107    }
108  ],
109  "links": {
110    "self": "/v2/issuers/{organizationId}/users/{userId}/locations?page[size]=1&filter[latitude]=39.9419429&filter[longitude]=-75.1446869&filter[radius]=10&include=offers,categories",
111    "prev": null,
112    "next": "/v2/issuers/{organizationId}/users/{userId}/locations?page[after]=NDMyNzQyODI3OTQw&page[size]=1&filter[latitude]=39.9419429&filter[longitude]=-75.1446869&filter[radius]=10&include=offers,categories"
113  },
114  "included": [
115    {
116      "type": "category",
117      "id": "65920081b524d126068de24a",
118      "attributes": {
119        "name": "Food & Beverage"
120      }
121    },
122    {
123      "type": "standardOffer",
124      "id": "5e27318c9b346f00087fbb5c",
125      "attributes": {
126        "name": "Worlds Greatest Chicken",
127        "terms": "Worlds Greatest Chicken offers are only available within US Locations.",
128        "purchaseChannel": [
129          "INSTORE"
130        ],
131        "userReward": {
132          "type": "PERCENT",
133          "value": 5.7
134        },
135        "startDate": "2022-01-01T05:00:00Z",
136        "expirationDate": "2022-01-01T05:00:00Z",
137        "minRewardAmount": {
138          "type": "CENTS",
139          "value": 500
140        },
141        "maxRewardAmount": {
142          "type": "CENTS",
143          "value": 2000
144        },
145        "minTransactionAmount": {
146          "type": "CENTS",
147          "value": 500
148        },
149        "maxTransactionAmount": {
150          "type": "CENTS",
151          "value": 2000
152        },
153        "maxRedemptions": 1,
154        "isTargeted": true,
155        "assets": [
156          {
157            "url": "http://attribution.getkard.com/logos/breakfastbunny_logo.png?subtype=IMG_VIEW&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D",
158            "alt": "",
159            "type": "IMG_VIEW"
160          },
161          {
162            "url": "https://attribution.getkard.com/public/banners/breakfast-bunny-banner.jpg?subtype=BANNER_VIEW&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D",
163            "alt": "",
164            "type": "BANNER_VIEW"
165          }
166        ],
167        "websiteUrl": "http://worldsgreatestchickent.test.com",
168        "description": "Worlds Greatest Chicken brings you the tastiest crispy, double fried spicy chicken in the world."
169      }
170    }
171  ]
172}
Retrieve national and local geographic locations that a specified user has eligible in-store offers at. Use this endpoint to build out your [map-specific UX experiences](/2024-10-01/api/getting-started#c-discover-clos-near-you-map-view). Please note that Longitude and Latitude fields are prioritized over State, City and Zipcode and are the recommended search pattern.<br/> <br/> <b>Required scopes:</b> `rewards:read`
Was this page helpful?
Previous

Notification Webhook

Next
Built with

Retrieve national and local geographic locations that a specified user has eligible in-store offers at. Use this endpoint to build out your map-specific UX experiences. Please note that Longitude and Latitude fields are prioritized over State, City and Zipcode and are the recommended search pattern.


Required scopes: rewards:read

Authentication

AuthorizationBearer

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

Path parameters

organizationIdstringRequired
Your issuer organization ID, provided by Kard
userIdstringRequired
The ID of the user as defined on the issuers system

Query parameters

page[size]integerOptional
page[after]stringOptional
page[before]stringOptional
filter[name]stringOptional
filter[city]stringOptional
filter[zipCode]stringOptional
filter[state]enumOptional
filter[category]enumOptional

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

filter[longitude]doubleOptional
filter[latitude]doubleOptional
filter[radius]integerOptional
sortenumOptional
If provided, response will be sorted by the specified fields
Allowed values:
includestringOptional

CSV list of included resources in the response (e.g “offers,categories”). Allowed values are offers and categories.

supportedComponentsenumOptional
UI component types to include in included offers.

Response

This endpoint returns an object.
datalist of objects
linksobject
Related links to the API call
includedlist of objects

Errors

400
Invalid Request
401
Unauthorized Error
404
Does Not Exist Error
500
Internal Server Error