---
title: "Create wallet messaging batch"
method: POST
path: "/api/v1/entities/{id}/messaging/wallet"
tags: ["Batches"]
---

# Create wallet messaging batch

`POST /api/v1/entities/{id}/messaging/wallet`

Create a new wallet messaging batch using segments, recipients, or a CSV file (via multipart/form-data).

The path parameter `{id}` is the entity **sending** the batch (your own entity). Recipients are defined separately in the request body via `segments`, `recipients`, or `csv`. Pass template and group tag segments can be combined to narrow the audience to passes that match both.

For more details, see the [Wallet Messaging](/documentation/bulk-operations/batch-notifications/guide) documentation.

## Request body

- CreateWalletMessagingBatch
  - `batch` union
    - object
      - `message` string, required — Message to be sent. Include %{variable} for dynamic content.
      - `scheduledAt` string, required — ISO8601 timestamp of when the batch is scheduled to be sent
      - `segments` union[], required — Target recipients of the message. Each segment targets by pass template (`passTemplateId`), pass group tags (`groupTag`/`groupTags`), or entity UUID (`entityId`). **To message passes filtered by both pass template and group tags, send one segment of each type together** - the batch then targets passes on that template that also carry at least one of the tags. An entity segment targets all passes in the entity and cannot be combined with a pass template segment. Provide at most one segment of each type. `segments[].entityId` must match the entity `{id}` in the request URL.
        - union
          - object
            - `passTemplateId` string — Pass Template UUID
          - object
            - `groupTag` string — Pass group tag
            - `groupTags` unknown[] — Pass group tags. Passes matching any of the listed tags are included.
              - …
          - object
            - `entityId` string — Entity UUID
    - object
      - `message` string, required — Message to be sent. Include %{variable} for dynamic content.
      - `scheduledAt` string, required — ISO8601 timestamp of when the batch is scheduled to be sent
      - `recipients` object[], required — Target recipients of the message. Must include at least one recipient.
        - `passId` string, required — UUID of the pass
        - `variables` object — Variables to be replaced in the message

## Response `202`

Accepted

- object
  - `data` SerializedWalletMessagingBatch
    - `id` string — UUID of the batch
    - `type` 'walletMessaging' — Type of batch
    - `attributes` object
      - `name` string — Friendly name of the batch, used for display purposes. Auto-generated if not provided
      - `status` 'validating' | 'scheduled' | 'failed' | 'sending' | 'successful' | 'completedWithErrors' | 'cancelled' — Status of the batch
      - `tag` string, nullable — Tag of the batch, used for grouping and filtering purposes
      - `content` string — Message content
      - `totalRecipients` integer — Total number of recipients in the batch
      - `completedAt` string — ISO8601 timestamp of when the batch was completed
      - `scheduledAt` string — ISO8601 timestamp of when the batch is scheduled to be sent
      - `errorsCsvUrl` string — If present, batch failed validation, or had some errors during delivery. URL to a CSV file containing errors and error details of the batch
  - `links` BatchSelfLink
    - `self` string — Self link to the batch record

## Other responses

- `401` — Error: Unauthorized

---

[API](https://skmtc.dev/passentry/apis/passentry-api.md) · [All operations](https://skmtc.dev/passentry/apis/passentry-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/passentry/passentry-api/revisions/3b24e067f9d9/schema)