--- title: "Create a Journal" method: POST path: "/v1/journals" tags: ["Journals"] --- # Create a Journal `POST /v1/journals` A journal can be JNLC (move cash) or JNLS (move shares), dictated by `entry_type`. Generally, journal requests are subject to approval and starts from the `pending` status. The status changes are propagated through the Event API. Under certain conditions agreed for the partner, such journal transactions that meet the criteria are executed right away. **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 journal. A subsequent request returns the previously created journal 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 journals. This allows safe retries on timeouts, network errors, or 5xx responses without risking duplicate journals. Use a client-generated unique value (e.g. UUID). ## Headers - `Idempotency-Key` string ## Request body - CreateJournalRequest — 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 Journal Fixture Rules - No Fixtures - anything below limit is executed immediately - anything above limit is pending until executed at EOD, - With Fixtures - any status = rejected will be rejected EOD - any status = pending will be pending forever - `amount` string — Required if `entry_type` = `JNLC` - `currency` string - `description` string — Max 1024 characters. Can include fixtures for amounts that are above the transaction limit - `entry_type` 'JNLC' | 'JNLS', required — This enum represents the various kinds of Journal alpaca supports. Current values are: - **JNLC** Journal Cash between accounts - **JNLS** Journal Securities between accounts - `from_account` string, uuid, required — The account_id you wish to journal from - `qty` string — Required if `entry_type` = `JNLS` - `symbol` string — Required if `entry_type` = `JNLS` - `to_account` string, uuid, required — The account_id you wish to journal to - `transmitter_account_number` string — Max 255 characters. See more details about [Travel Rule](https://alpaca.markets/docs/broker/integration/funding/#travel-rule) in our main documentation. - `transmitter_address` string — Max 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 — Max 255 characters. See more details about [Travel Rule](https://alpaca.markets/docs/broker/integration/funding/#travel-rule) in our main documentation. - `transmitter_name` string — Max 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 — RFC 3339 format. See more details about [Travel Rule](https://alpaca.markets/docs/broker/integration/funding/#travel-rule) in our main documentation. ## Response `200` The New Journal object - union - object — Represents a cash or security transfer between accounts, as specified by the `entry_type` parameter. - `created_at` string, date-time - `entry_type` 'JNLC' | 'JNLS', required — JNLS - `from_account` string, uuid, required — The account ID that initiates the journal - account_status must equal to ACTIVE or CLOSE - `id` string, uuid, required — The journal ID - `settle_date` string, date, nullable — Date string in "%Y-%m-%d" format - `status` 'pending' | 'canceled' | 'executed' | 'activity_created' | 'queued' | 'rejected' | 'deleted' | 'refused' | 'sent_to_clearing' | 'correct' — 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. - `to_account` string, uuid, required — The account ID that received the journal - account_status must equal to ACTIVE - `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 - `currency` string — Currency denomination of the journal. USD by default. - `description` string - `price` string — The price of the security journaled - `qty` string — The quantity of the securities journaled - `symbol` string — The symbol of the security journaled - `system_date` string — Date string in "%Y-%m-%d" format - object — Represents a cash or security transfer between accounts, as specified by the `entry_type` parameter. - `created_at` string, date-time - `entry_type` 'JNLC' | 'JNLS', required — JNLC - `from_account` string, uuid, required — account ID the shares go from - `id` string, uuid, required — journal ID - `settle_date` string, date, nullable — Settlement date for the journal. Absent or `null` until the journal settles (for example, while `status` is `queued` or `pending`). - `status` 'pending' | 'canceled' | 'executed' | 'activity_created' | 'queued' | 'rejected' | 'deleted' | 'refused' | 'sent_to_clearing' | 'correct' — 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. - `to_account` string, uuid, required — account ID the shares go to - `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 - `currency` string — Currency denomination of the journal. USD by default. - `description` string — ID the amount goes to. Only valid for JNLC journals. Null for JNLS. - `net_amount` string, decimal, required — Only valid for JNLC journals. Null for JNLS. - `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 — Only valid for JNLC journals. Null for JNLS. ## Other responses - `400` — One of the parameters is invalid. - `403` — The amount requested to move is not available. - `404` — One of the account is not found. - `422` — Unprocessable Entity. Returned when an idempotency key is reused with a different request body. --- [API](https://skmtc.net/alpacahq/apis/gift-city-extensions-api.md) · [All operations](https://skmtc.net/alpacahq/apis/gift-city-extensions-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/alpacahq/gift-city-extensions-api/revisions/62e3378bb273/schema)