> This page is for version 2024-10-01 (default). > For other versions, use one of these documentation indexes: > - 2024-10-01 (default): https://docs.getkard.com/2024-10-01/llms.txt > - Legacy: https://docs.getkard.com/legacy/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getkard.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server. # List GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/placements List placements belonging to the authenticated organization Reference: https://docs.getkard.com/api/organizations/placements/list ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://rewards-api.getkard.com` (Production, default) - `https://test-rewards-api.getkard.com` (Sandbox) ## Request ### Path parameters - `organizationId` (string, required) — Unique identifier of the organization ### Query parameters - `filter[type]` (enum, optional) — Filter by placement type (placement, placementPushNotification, placementEmail, placementBatchActivation, or placementGroup) - Allowed values: `placement`, `placementPushNotification`, `placementEmail`, `placementBatchActivation`, `placementGroup` - `filter[name]` (string, optional) — Filter by exact placement name (unique within an organization per type) - `filter[contentStrategyId]` (string, optional) — Filter by the ID of the content strategy linked to the placement - `include` (string, optional) — CSV list of related resources to embed in the `included` array. Supported paths: `contentStrategy` (the direct content strategy of a non-batch placement), `slots` (the slot resources of a batch-activation or group placement), `slots.placement` (and the placement each slot references), and `slots.placement.contentStrategy` (and the content strategy of each referenced placement). Dotted paths implicitly include all intermediate resources. - `page[after]` (string, optional) — Cursor value for the next page of results - `page[size]` (integer, optional) — Maximum number of records to return [1 - 200] (default = 200) ## Response ### 200 Paginated list of placements - `data` (list of PlacementFormatUnion, required) — Array of placement resources - `included` (list of IncludedResource, optional) — Related resources requested via the `include` query parameter. Each entry is keyed by its `type` discriminant (`contentStrategy`, `batchActivationSlot`, `placement`, `placementPushNotification`, `placementEmail`). - `links` (Links, optional) — Related links to the API call - `meta` (OrganizationPaginationMetadata, optional) — Pagination metadata ## Errors ### 401 Unauthorized Error - `errors` (list of ErrorObject, required) ### 403 Forbidden Error - `errors` (list of ErrorObject, required) ### 400 Invalid Request - `errors` (list of ErrorObject, required) ### 404 Does Not Exist Error - `errors` (list of ErrorObject, required) ### 500 Internal Server Error - `errors` (list of ErrorObject, required) ## Types ### PlacementFormatUnion Discriminated union for placement resources keyed on type - `type`: `placement` - `attributes` (PlacementAttributes, required) — Attributes for a standard placement - `id` (string, required) — Unique identifier of the placement (UUID v7) - `relationships` (PlacementRelationships, optional) — JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. - `type`: `placementPushNotification` - `attributes` (PushNotificationPlacementAttributes, required) — Attributes for a push-notification placement - `id` (string, required) — Unique identifier of the placement (UUID v7) - `relationships` (PlacementRelationships, optional) — JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. - `type`: `placementEmail` - `attributes` (EmailPlacementAttributes, required) — Attributes for an email placement - `id` (string, required) — Unique identifier of the placement (UUID v7) - `relationships` (PlacementRelationships, optional) — JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. - `type`: `placementBatchActivation` - `attributes` (BatchActivationPlacementAttributes, required) — Attributes for a batch-activation placement. Slot detail is exposed via `relationships.slots` (resource identifiers) and the `batchActivationSlot` entries in `included`; request `?include=slots` (or a deeper path) to get the slot details. - `id` (string, required) — Unique identifier of the placement (UUID v7) - `relationships` (SlottedPlacementRelationships, required) — JSON:API relationships for the placement. Always present on a batch-activation placement; the `slots` to-many relationship lists the slot resource identifiers. - `type`: `placementGroup` - `attributes` (GroupPlacementAttributes, required) — Attributes for a group placement. A group is configured like a batch-activation placement but has no refreshInterval. Slot detail is exposed via `relationships.slots` (resource identifiers) and the `batchActivationSlot` entries in `included`; request `?include=slots` (or a deeper path) to get the slot details. - `id` (string, required) — Unique identifier of the placement (UUID v7) - `relationships` (SlottedPlacementRelationships, required) — JSON:API relationships for the placement. Always present on a group placement; the `slots` to-many relationship lists the slot resource identifiers. ### IncludedResource Discriminated union of every resource type that can appear in the `included` array. The shape of each branch matches the corresponding primary-data resource (same attributes and relationships), keyed on the JSON:API `type` discriminant. - `type`: `contentStrategy` - `attributes` (ContentStrategyAttributes, required) — Attributes for a content strategy - `id` (string, required) - `type`: `batchActivationSlot` - `attributes` (BatchActivationSlotAttributes, required) — Attributes block for a `batchActivationSlot` resource. - `id` (string, required) - `relationships` (BatchActivationSlotRelationships, required) — Relationship block for a `batchActivationSlot` resource. - `type`: `placement` - `attributes` (PlacementAttributes, required) — Attributes for a standard placement - `id` (string, required) — Unique identifier of the placement (UUID v7) - `relationships` (PlacementRelationships, optional) — JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. - `type`: `placementPushNotification` - `attributes` (PushNotificationPlacementAttributes, required) — Attributes for a push-notification placement - `id` (string, required) — Unique identifier of the placement (UUID v7) - `relationships` (PlacementRelationships, optional) — JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. - `type`: `placementEmail` - `attributes` (EmailPlacementAttributes, required) — Attributes for an email placement - `id` (string, required) — Unique identifier of the placement (UUID v7) - `relationships` (PlacementRelationships, optional) — JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. ### Links Related links to the API call - `self` (string, required) - `prev` (string, optional) - `next` (string, optional) ### OrganizationPaginationMetadata Pagination metadata for organization list responses - `pageSize` (integer, required) — Number of items per page - `hasNextPage` (boolean, required) — Whether more pages are available ### ErrorObject - `status` (string, required) — Status code returned from the request - `title` (string, required) — Name of error - `detail` (string, required) — Description of the specific occurance of the error - `source` (ErrorSource, optional) — An object containing a reference to the primary source of the error - `id` (string, optional) — The id of the resource which caused the error. Always returned for multi-status errors. ### PlacementAttributes Attributes for a standard placement - `name` (string, required) — Name of the placement - `organizationId` (string, required) — ID of the organization this placement belongs to - `availableSlots` (integer, required) — Number of available slots - `displayName` (string, optional) — Cardholder-facing title for the section, if one was set. When absent, clients fall back to their own default label. - `contentStrategyId` (string, optional) — ID of the content strategy linked to this placement, if any. Retained alongside `relationships.contentStrategy` for backward compatibility. ### PlacementRelationships Relationship block for non-batch placements. Mirrors the `contentStrategyId` attribute so JSON:API clients can walk the graph. - `contentStrategy` (ToOneRelationship, optional) — Relationship to the content strategy that powers this placement. Present whenever the placement has been linked to a content strategy (`data.id` will be set). Omitted entirely when no content strategy is linked. ### PushNotificationPlacementAttributes Attributes for a push-notification placement - `name` (string, required) — Name of the placement - `status` (enum, required) — Whether the placement's scheduled deliveries are paused. Has no effect on content serving. - Allowed values: `ACTIVE`, `INACTIVE` - `organizationId` (string, required) — ID of the organization this placement belongs to - `cadence` (Cadence, required) — Delivery cadence for the notification - `contentStrategyId` (string, optional) — ID of the content strategy linked to this placement, if any. Retained alongside `relationships.contentStrategy` for backward compatibility. ### EmailPlacementAttributes Attributes for an email placement - `name` (string, required) — Name of the placement - `status` (enum, required) — Whether the placement's scheduled deliveries are paused. Has no effect on content serving. - Allowed values: `ACTIVE`, `INACTIVE` - `organizationId` (string, required) — ID of the organization this placement belongs to - `availableSlots` (integer, required) — Number of available slots - `cadence` (Cadence, required) — Delivery cadence for the email - `contentStrategyId` (string, optional) — ID of the content strategy linked to this placement, if any. Retained alongside `relationships.contentStrategy` for backward compatibility. ### BatchActivationPlacementAttributes Attributes for a batch-activation placement. Slot detail is exposed via `relationships.slots` (resource identifiers) and the `batchActivationSlot` entries in `included`; request `?include=slots` (or a deeper path) to get the slot details. - `name` (string, required) — Name of the placement - `organizationId` (string, required) — ID of the organization this placement belongs to - `refreshInterval` (string, required) — ISO-8601 duration that controls how often the activation cohort refreshes (e.g. "P7D" for weekly). ### SlottedPlacementRelationships Relationship block for a batch-activation or group placement. - `slots` (ToManyRelationship, required) — Resource identifiers for the slots that make up the placement. Each entry corresponds to a `batchActivationSlot` resource that appears in `included` when the request asks for `slots` (or any deeper path that implies it). ### GroupPlacementAttributes Attributes for a group placement. A group is configured like a batch-activation placement but has no refreshInterval. Slot detail is exposed via `relationships.slots` (resource identifiers) and the `batchActivationSlot` entries in `included`; request `?include=slots` (or a deeper path) to get the slot details. - `name` (string, required) — Name of the placement - `organizationId` (string, required) — ID of the organization this placement belongs to ### ContentStrategyAttributes Attributes for a content strategy - `name` (string, required) — Name of the content strategy (unique within an organization) - `organizationId` (string, required) — ID of the organization this content strategy belongs to - `filters` (ContentStrategyFilters, required) — Filters applied when selecting offers for the strategy - `categories` (list of enum, required) — Merchant categories to include - Allowed values: `Arts & Entertainment`, `Baby, Kids & Toys`, `Books & Digital Media`, `Clothing, Shoes & Accessories`, `Computers, Electronics & Software`, `Convenience`, `Gas`, `Department Stores`, `Food & Beverage`, `Health & Beauty`, `Home & Garden`, `Miscellaneous`, `Occasions & Gifts`, `Pets`, `Sports & Outdoors`, `Supplies & Services`, `Travel` - `categoryExclusions` (list of enum, required) — Merchant categories to exclude - Allowed values: `Arts & Entertainment`, `Baby, Kids & Toys`, `Books & Digital Media`, `Clothing, Shoes & Accessories`, `Computers, Electronics & Software`, `Convenience`, `Gas`, `Department Stores`, `Food & Beverage`, `Health & Beauty`, `Home & Garden`, `Miscellaneous`, `Occasions & Gifts`, `Pets`, `Sports & Outdoors`, `Supplies & Services`, `Travel` - `merchantExclusions` (list of string, required) — Merchant IDs to exclude - `sort` (enum, optional) — Sort applied when selecting offers for the strategy - Allowed values: `NEWLY_LIVE`, `EXPIRING_SOON`, `HIGHEST_CASHBACK`, `PERSONALIZED`, `OFFERS_NEAR_YOU` ### BatchActivationSlotAttributes Attributes block for a `batchActivationSlot` resource. - `alias` (string, required) — Customer-defined alias for the slot, unique within the placement. - `shortDescription` (string, optional) — Optional short description of the slot, limited to 50 characters. ### BatchActivationSlotRelationships Relationship block for a `batchActivationSlot` resource. - `placement` (ToOneRelationship, required) — Reference to the placement that fills this slot. The referenced placement provides the slot's content strategy and offer-count cap; request `?include=slots.placement` to embed it in `included`. ### ErrorSource - `pointer` (string, optional) — A JSON pointer to the value in the request document that caused the error - `parameter` (string, optional) — A string indicating which URI query parameter caused the error - `header` (string, optional) — A string indicating the name of a single request header which caused the error ### ToOneRelationship A JSON:API to-one relationship payload. - `data` (ResourceIdentifier, optional) — The linked resource identifier, or null when the relationship is present but unlinked. ### Cadence Cadence schedule for push notification and email placements - `frequency` (enum, required) — Delivery frequency - Allowed values: `DAILY`, `WEEKLY`, `MONTHLY` - `timeOfDay` (string, optional) — Optional time of day in HH:mm format (24-hour, UTC) - `dayOfWeek` (enum, optional) — Day of the week to deliver (used when frequency is WEEKLY, defaults to MON) - Allowed values: `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, `SUN` - `dayOfMonth` (integer, optional) — Day of the month to deliver, 1-31 (used when frequency is MONTHLY, defaults to 1) ### ToManyRelationship A JSON:API to-many relationship payload. - `data` (list of ResourceIdentifier, required) — The linked resource identifiers. ### ContentStrategyFilters Filters applied when selecting offers for a content strategy - `categories` (list of string, optional) — Merchant categories to include - `categoryExclusions` (list of string, optional) — Merchant categories to exclude - `merchantExclusions` (list of string, optional) — Merchant IDs to exclude - `offerFeatures` (list of enum, optional) — Offer features to filter by - Allowed values: `INTERACTIVE` ### ResourceIdentifier A reference to another resource by type and id. - `type` (string, required) — Discriminant of the referenced resource (e.g. `contentStrategy`). - `id` (string, required) — Identifier of the referenced resource. ## Examples **Response** ```json { "data": [ { "type": "placement", "attributes": { "name": "name", "organizationId": "organizationId", "availableSlots": 1, "displayName": "displayName", "contentStrategyId": "contentStrategyId" }, "id": "id", "relationships": { "contentStrategy": { "data": { "type": "type", "id": "id" } } } }, { "type": "placement", "attributes": { "name": "name", "organizationId": "organizationId", "availableSlots": 1, "displayName": "displayName", "contentStrategyId": "contentStrategyId" }, "id": "id", "relationships": { "contentStrategy": { "data": { "type": "type", "id": "id" } } } } ], "included": [ { "type": "contentStrategy", "attributes": { "name": "name", "organizationId": "organizationId", "filters": { "categories": [ "categories", "categories" ], "categoryExclusions": [ "categoryExclusions", "categoryExclusions" ], "merchantExclusions": [ "merchantExclusions", "merchantExclusions" ], "offerFeatures": [ "INTERACTIVE", "INTERACTIVE" ] }, "categories": [ "Arts & Entertainment", "Arts & Entertainment" ], "categoryExclusions": [ "Arts & Entertainment", "Arts & Entertainment" ], "merchantExclusions": [ "merchantExclusions", "merchantExclusions" ], "sort": "NEWLY_LIVE" }, "id": "id" }, { "type": "contentStrategy", "attributes": { "name": "name", "organizationId": "organizationId", "filters": { "categories": [ "categories", "categories" ], "categoryExclusions": [ "categoryExclusions", "categoryExclusions" ], "merchantExclusions": [ "merchantExclusions", "merchantExclusions" ], "offerFeatures": [ "INTERACTIVE", "INTERACTIVE" ] }, "categories": [ "Arts & Entertainment", "Arts & Entertainment" ], "categoryExclusions": [ "Arts & Entertainment", "Arts & Entertainment" ], "merchantExclusions": [ "merchantExclusions", "merchantExclusions" ], "sort": "NEWLY_LIVE" }, "id": "id" } ], "links": { "self": "self", "prev": "prev", "next": "next" }, "meta": { "pageSize": 1, "hasNextPage": true } } ``` **SDK Code** ```python import requests url = "https://rewards-api.getkard.com/v2/issuers/organizationId/placements" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://rewards-api.getkard.com/v2/issuers/organizationId/placements'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://rewards-api.getkard.com/v2/issuers/organizationId/placements" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://rewards-api.getkard.com/v2/issuers/organizationId/placements") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/organizationId/placements") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://rewards-api.getkard.com/v2/issuers/organizationId/placements', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organizationId/placements"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organizationId/placements")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```