---
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`. When using `segments[].entityId`, that UUID targets passes belonging to that entity as recipients and may be the same as, or different from, the path `{id}`.

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 can target by pass template (`passTemplateId`), pass group tag (`groupTag`/`groupTags`), or entity UUID (`entityId`). Note: `segments[].entityId` selects passes belonging to that entity as recipients and is independent of the entity `{id}` in the request URL (which identifies the entity sending the batch).
        - union
          - object
            - `passTemplateId` string — Pass Template UUID
          - object
            - `groupTag` string — Pass group tag
            - `groupTags` unknown[] — Pass group tags
              - …
          - 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.net/passentry/apis/passentry-api.md) · [All operations](https://skmtc.net/passentry/apis/passentry-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/passentry/passentry-api/versions/2c7dc0306b04/schema)