---
title: "Create On Demand"
method: POST
path: "/v2/issuers/{organizationId}/placements/onDemand"
tags: ["Organizations > Placements"]
---

# Create On Demand

`POST /v2/issuers/{organizationId}/placements/onDemand`

## Request

- Base URL: `https://rewards-api.getkard.com`
- URL: `https://rewards-api.getkard.com/v2/issuers/{organizationId}/placements/onDemand`
- Auth: HTTP bearer

Fire a one-off ad-hoc push or email notification batch for the organization without a persistent placement. Pin the audience with exactly one of `placementId` or `offerIds` (supplying both or neither is rejected). Rate limited to once per 24 hours per issuer: a request inside the window returns 429 with a `Retry-After` header indicating how many seconds to wait. On success the workflow is triggered and a 202 is returned with the recorded request id.

## Path parameters

- `organizationId` string, required

## Request body

- OrganizationsPlacementsCommonCreateOnDemandPlacementRequestBody: Request body for firing an on-demand placement
  - `data` OrganizationsPlacementsCommonCreateOnDemandPlacementData, required: JSON:API data envelope for an on-demand placement fire
    - `type` string, required: JSON:API resource type discriminant; always `placementOnDemand`.
    - `attributes` OrganizationsPlacementsCommonCreateOnDemandPlacementAttributes, required: Attributes for an on-demand placement fire
      - `medium` 'push' | 'email', required: Delivery medium for an on-demand placement fire
      - `placementId` string: ID of an existing placement to fire. Mutually exclusive with `offerIds`; provide exactly one.
      - `offerIds` string[]: IDs of the specific offers to pin the fire to (at least one). Mutually exclusive with `placementId`; provide exactly one.

## Response `202`

The ad-hoc request was accepted and the workflow was triggered

- OrganizationsPlacementsCommonOnDemandPlacementResponse: Envelope for an accepted on-demand placement request
  - `data` OrganizationsPlacementsCommonOnDemandPlacementResource, required: The accepted on-demand placement request resource
    - `type` string, required: JSON:API resource type discriminant; always `placementOnDemand`.
    - `id` string, required: Identifier of the recorded ad-hoc placement request (the request id).
    - `attributes` OrganizationsPlacementsCommonOnDemandPlacementResourceAttributes, required: Attributes of an accepted on-demand placement request
      - `status` 'queued', required: Processing status of an accepted on-demand placement request

## Other responses

- `400`: Error response with status 400
- `401`: Error response with status 401
- `403`: Error response with status 403
- `404`: Error response with status 404
- `429`: The issuer's traffic grew faster than its allowed rate, or the endpoint's own limit was reached. If the response includes a `Retry-After` header, wait that many seconds before retrying. See [Rate Limits](/2024-10-01/api/integration-guides/rate-limits).
- `500`: Error response with status 500

## Changes

- **2026-10-27** `f23dfd7fffef`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getkard/apis/getkard-2/changes/v2/issuers/:organizationId/placements/onDemand/post.md)

---

[API](https://skmtc.dev/getkard/apis/getkard-2.md) - [All operations](https://skmtc.dev/getkard/apis/getkard-2/llms.txt) - [OpenAPI document](https://skmtc.dev/getkard/apis/getkard-2/revisions/bd47764afa21?raw)