---
title: "Create a Batch Journal Transaction (One-to-Many)"
method: POST
path: "/v1/journals/batch"
tags: ["Journals"]
---

# Create a Batch Journal Transaction (One-to-Many)

`POST /v1/journals/batch`

## Request

- Base URL: `https://broker-api.giftcity.sandbox.in.alpaca.markets`
- URL: `https://broker-api.giftcity.sandbox.in.alpaca.markets/v1/journals/batch`
- Auth: HTTP basic

You can create a batch of journal requests by using this endpoint. This is enabled on JNLC type Journals for now only.

Every single request must be valid for the entire batch operation to succeed.

In the case of a successful request, the response will contain an array of journal objects with an extra attribute error_message in the case when a specific account fails to receive a journal.

**Idempotency**: When the `Idempotency-Key` header is supplied, this endpoint is
idempotent. Multiple requests with the same key and identical request body will
create only one batch. A subsequent request returns the previously created
batch with the same response (no duplicate is created). If the same key is used
with a different request body, the API returns `422 Unprocessable Entity`.

**Recommended for production**: Always supply `Idempotency-Key` when creating
journal batches. This allows safe retries on timeouts, network errors, or 5xx responses
without risking duplicate batches. Use a client-generated unique value (e.g. UUID).

## Headers

- `Idempotency-Key` string

## Request body

- BatchJournalRequest: Journals API allows you to move cash or securities from one account to another. This model represents the fields you can specify when creating a request of many Journals out of one account to many others at once.
  - `correspondent` string: The 4-character correspondent code
  - `entries` object[], required: An array of objects describing which accounts you want to move funds into and how much to move into each account
    - `amount` string, nullable, required: Journal amount in the entry's `currency`
    - `currency` string, nullable: The currency of the journal. Defaults to the system currency (for example, USD in the US or EUR in the EU) when omitted. Correspondents with local currency trading enabled must send this field, and the value must be the system currency or one of the correspondent's enabled currencies. All entries in a batch should use the same currency.
    - `description` string: Journal entry description, gets returned in the response
    - `qty` string, nullable
    - `symbol` string
    - `to_account` string, uuid, required: The ID of the account that you want to journal funds into
    - `transmitter_account_number` string: Only valid for JNLC journals. Null for JNLS.max 255 characters
    - `transmitter_address` string: Only valid for JNLC journals. Null for JNLS.max 255 characters
    - `transmitter_financial_institution` string: Only valid for JNLC journals. Null for JNLS.max 255 characters
    - `transmitter_name` string: Only valid for JNLC journals. Null for JNLS. Max 255 characters.
    - `transmitter_timestamp` string, date-time
  - `entry_type` 'JNLC', required: Only supports `JNLC` for now
  - `from_account` string, uuid, required: The account id that is the originator of the funds being moved. Most likely is your Sweep Firm Account

## Response `200`

an array of journal objects with an extra attribute error_message in the case when a specific account fails to receive a journal.

- BatchJournalResponse[]
  - union: A forward batch journal result selected by `entry_type`, with an optional non-empty failure message.
    - BatchJournalResponseJNLC: A cash journal result returned by the forward batch endpoint.
      - `created_at` string, date-time: The creation time when supplied by the endpoint.
      - `currency` string, required: Currency denomination of the journal.
      - `description` string, required: The journal description.
      - `from_account` string, uuid, required: The account ID that initiated the journal.
      - `id` string, uuid, required: The journal ID.
      - `net_amount` string, decimal, nullable, required: The cash amount, or null when not applicable.
      - `price` string, decimal, nullable, required: The journaled security price, or null when not applicable.
      - `qty` string, decimal, nullable, required: The journaled security quantity, or null when not applicable.
      - `settle_date` string, date, nullable, required: The settlement date, or null until one is assigned.
      - `status` 'pending' | 'canceled' | 'executed' | 'activity_created' | 'queued' | 'rejected' | 'deleted' | 'refused' | 'sent_to_clearing' | 'correct', required: Represents the status that a Journal instance can be in. **Current Values** queued Journal in queue to be processed. Journal is not processed yet. sent_to_clearing Journal sent to be processed by Alpaca's booking system. The journal is not processed yet. pending Journal pending to be processed as it requires manual approval from Alpaca operations (for example due to hitting JNLC daily limits). executed Journal executed and balances updated for both sides of the journal transaction. This is not a final status, journals can be reversed if there is an error. activity_created Non-trade activity has been created for journal (JNLC v2-only). rejected Journal rejected. Please try again. canceled Journal canceled. This is a **FINAL** status. refused Journal refused. Please try again. deleted Journal deleted. This is a **FINAL** status. correct Journal is corrected. Previously executed journal is cancelled and a new journal is corrected amount is created. This is a **FINAL** status.
      - `symbol` string, nullable, required: The journaled security symbol, or null for a cash journal.
      - `system_date` string, date, nullable, required: The booking-system date, or null until one is assigned.
      - `to_account` string, uuid, required: The account ID that received the journal.
      - `transmitter_info` TransmitterInfo: Information about the transmitter to satisfy travel rule requirements. Required if the requesting correspondent qualifies as a financial institution
        - `originator_bank_account_number` string: Required if the requesting correspondent qualifies as a financial institution
        - `originator_bank_name` string: Required if the requesting correspondent qualifies as a financial institution
        - `originator_city` string
        - `originator_country` string: Required if the requesting correspondent qualifies as a financial institution
        - `originator_full_name` string: Required if the requesting correspondent qualifies as a financial institution
        - `originator_postal_code` string
        - `originator_state` string
        - `originator_street_address` string
        - `other_identifying_information` string: Used to facilitate transfer lookup in the event it is required. Recommended to be the originating bank's reference number for the transfer
      - `entry_type` 'JNLC', required: Cash journal discriminator value.
      - `transmitter_account_number` string: Optional for JNLC journals. Maximum 255 characters. See more details about [Travel Rule](https://alpaca.markets/docs/broker/integration/funding/#travel-rule) in our main documentation.
      - `transmitter_address` string: Optional for JNLC journals. Maximum 255 characters. See more details about [Travel Rule](https://alpaca.markets/docs/broker/integration/funding/#travel-rule) in our main documentation.
      - `transmitter_financial_institution` string: Optional for JNLC journals. Maximum 255 characters. See more details about [Travel Rule](https://alpaca.markets/docs/broker/integration/funding/#travel-rule) in our main documentation.
      - `transmitter_name` string: Optional for JNLC journals. Maximum 255 characters. See more details about [Travel Rule](https://alpaca.markets/docs/broker/integration/funding/#travel-rule) in our main documentation.
      - `transmitter_timestamp` string, date-time: Optional for JNLC journals. RFC 3339 format. See more details about [Travel Rule](https://alpaca.markets/docs/broker/integration/funding/#travel-rule) in our main documentation.
      - `error_message` string: Description of why this journal transaction failed. Omitted for successful results.
    - BatchJournalResponseJNLS: A securities journal result that preserves discriminator-complete batch response modeling, although current public batch requests support JNLC only.
      - `created_at` string, date-time: The creation time when supplied by the endpoint.
      - `currency` string, required: Currency denomination of the journal.
      - `description` string, required: The journal description.
      - `from_account` string, uuid, required: The account ID that initiated the journal.
      - `id` string, uuid, required: The journal ID.
      - `net_amount` string, decimal, nullable, required: The cash amount, or null when not applicable.
      - `price` string, decimal, nullable, required: The journaled security price, or null when not applicable.
      - `qty` string, decimal, nullable, required: The journaled security quantity, or null when not applicable.
      - `settle_date` string, date, nullable, required: The settlement date, or null until one is assigned.
      - `status` 'pending' | 'canceled' | 'executed' | 'activity_created' | 'queued' | 'rejected' | 'deleted' | 'refused' | 'sent_to_clearing' | 'correct', required: Represents the status that a Journal instance can be in. **Current Values** queued Journal in queue to be processed. Journal is not processed yet. sent_to_clearing Journal sent to be processed by Alpaca's booking system. The journal is not processed yet. pending Journal pending to be processed as it requires manual approval from Alpaca operations (for example due to hitting JNLC daily limits). executed Journal executed and balances updated for both sides of the journal transaction. This is not a final status, journals can be reversed if there is an error. activity_created Non-trade activity has been created for journal (JNLC v2-only). rejected Journal rejected. Please try again. canceled Journal canceled. This is a **FINAL** status. refused Journal refused. Please try again. deleted Journal deleted. This is a **FINAL** status. correct Journal is corrected. Previously executed journal is cancelled and a new journal is corrected amount is created. This is a **FINAL** status.
      - `symbol` string, nullable, required: The journaled security symbol, or null for a cash journal.
      - `system_date` string, date, nullable, required: The booking-system date, or null until one is assigned.
      - `to_account` string, uuid, required: The account ID that received the journal.
      - `transmitter_info` TransmitterInfo: Information about the transmitter to satisfy travel rule requirements. Required if the requesting correspondent qualifies as a financial institution
        - `originator_bank_account_number` string: Required if the requesting correspondent qualifies as a financial institution
        - `originator_bank_name` string: Required if the requesting correspondent qualifies as a financial institution
        - `originator_city` string
        - `originator_country` string: Required if the requesting correspondent qualifies as a financial institution
        - `originator_full_name` string: Required if the requesting correspondent qualifies as a financial institution
        - `originator_postal_code` string
        - `originator_state` string
        - `originator_street_address` string
        - `other_identifying_information` string: Used to facilitate transfer lookup in the event it is required. Recommended to be the originating bank's reference number for the transfer
      - `entry_type` 'JNLS', required: Securities journal discriminator value.
      - `error_message` string: Description of why this journal transaction failed. Omitted for successful results.

## Other responses

- `422`: Unprocessable Entity. Returned when an idempotency key is reused with a different request body.

---

[API](https://skmtc.dev/alpacahq/apis/broker-api.md) - [All operations](https://skmtc.dev/alpacahq/apis/broker-api/llms.txt) - [OpenAPI document](https://skmtc.dev/alpacahq/apis/broker-api/revisions/381b1ecb3ccc?raw)