---
title: "Create earmark (Pismo account ID)"
method: POST
path: "/cash-management/v2/earmarks"
tags: ["Earmarking (Pismo account ID)"]
---

# Create earmark (Pismo account ID)

`POST /cash-management/v2/earmarks`

Create an earmark.
An account holder can use an earmark to hold needed funds in reserve until a specified release date and time.

Optionally, the account holder can schedule a payout for the release date and time. At that time, an automatic process releases the earmarked funds and settles the payout.

It's possible to force the creation of an earmark by not performing any regular validations, such as account status, account balance, or flex controls validations.

This endpoint generates the following events:
- [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1)
- [Account balance changed](https://developers.pismo.io/events/docs/account-balances-balance-change-1)
- [Account balance changed (Availables)](https://developers.pismo.io/events/docs/availables-change-available-1)
- [Transaction created](https://developers.pismo.io/events/docs/transaction-creation-1)
- [Earmark created, updated, or canceled](https://developers.pismo.io/events/docs/corporate-earmark-1) with `CREATED` action.

**NOTES**:
  - This endpoint requires an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.

## Request body

- CoreAccountBasedCreateEarmarkRequestV2
  - `amount` number, float, required — Earmark amount<br> `minimum: 0.01` `maximum: 18446744073709551617`
  - `internal_operation` InternalOperation2, required — Data used in transactions executed internally during the request.
    - `tracking_id` string, required — Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates.
    - `business_date` string, date — Specifying a `business_date` value impacts the account balance history.<br> <b>Notes</b>: - The business date is in ISO 8601 format. - The business date allows users to designate the balance history cycle in which a payment is posted. - You can specify a `business_date` within the current working day or up to one working day before or after.
    - `validation_rules` ValidationRules — Rules that determine which validations are executed during the payment process.<br> Available validation rules: - `LEDGER` - `ACCOUNT_STATUS` - `FLEX_CONTROLS` - `RATES`<br> `force` is only supported for `LEDGER`. `override` is supported for `ACCOUNT_STATUS`, `FLEX_CONTROLS`, and `RATES`.
    - `metadata` CancelEarmarkMetadata — Key-value pairs containing data intended for storage in the Pismo system.<br> **Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis).
  - `account_id` integer, required — Account ID generated by [Create account application](https://developers.pismo.io/pismo-docs/reference/post-acquisitions-v3-s2s-applications).<br> `minimum: 1` `maximum: 4294967295`
  - `earmark_id` string — Optional earmark ID. If `earmark_id` already exists, the caller receives a 409 error. If provided, the earmark is created with this ID. If not provided, a random earmark ID is generated.
  - `description` string — Earmark description
  - `release_datetime` string, date-time — RFC 3339 date/time for earmark release. Used to schedule a cash-out (usually a payment) at the specified release date and time. At `release_datetime`, an automatic process releases the earmarked funds and settles the cash-out. If no `release_datetime` is set, the earmarked amount is held indefinitely until the customer cancels the earmark.
  - `force_post` boolean — If the account has any reason-based force debit payment restrictions, and the force earmark creation violates any of those restrictions, it fails. The reasons that restrict force debit operations are: - `CREDIT ONLY`: No force debit allowed - `ANY`: No force allowed - `MANUAL`: No force allowed

## Response `201`

Created

- EarmarkResponse
  - `earmark_id` string — Earmark ID. Used as the primary key for query and update operations. It has the same value as the tracking ID, if one is provided. Generated by [Create Earmark](https://developers.pismo.io/pismo-docs/reference/post-corporate-v2-earmarks).
  - `account_id` integer — Account ID generated by [Create Corporate Account](https://developers.pismo.io/pismo-docs/reference/post-account).<br> `minimum: 1` `maximum: 4294967295`
  - `external_account_id` string — External ID of the account on which the earmark is created. Should be the same `external_account_id` that was used to log in. Should be the same `external_account_id` used in [Create Corporate Account](https://developers.pismo.io/pismo-docs/reference/post-account).
  - `description` string — Earmark description
  - `amount` number, float — Earmark amount<br> `minimum: 0.01` `maximum: 18446744073709551617`
  - `balance` number — Earmark balance. Initially equal to the earmarked amount and decreases as the reserved funds are used up or decreased in a decrease operation. It can also increase if an increase operation is performed.<br> `minimum: 0` `maximum: 18446744073709551617`
  - `release_datetime` string, date-time — RFC 3339 date/time for earmark release. Used to schedule a cash-out (usually a payment) at the specified release date and time. At `release_datetime`, an automatic process releases the earmarked funds and settles the cash-out. If no `release_datetime` is set, the earmarked amount is held indefinitely until the customer cancels the earmark.
  - `internal_operations` InternalOperation[] — List of internal operations performed to hold or release the earmark funds.
    - `tracking_id` string, required — Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates.
    - `business_date` string, date — Specifying a `business_date` value impacts the account balance history.<br> <b>Notes</b>: - The business date is in ISO 8601 format. - The business date allows users to designate the balance history cycle in which a payment is posted. - You can specify a `business_date` within the current working day or up to one working day before or after.
    - `type` 'HOLD_FUNDS' | 'RELEASE_FUNDS' | 'INCREASE' | 'DECREASE' — Internal operation type.<br> `minLength: 1` `maxLength: 13`
    - `processing_code` string — Processing code for the debit transaction. If `split_transaction` is `false` (the default), each installment payment is recorded as one debit transaction equal to the installment amount minus the discount, and `processing_code` is the processing code for that transaction. If `split_transaction` is `true`, each installment payment is recorded as two transactions: a debit transaction for the installment amount and a credit transaction for the discount. In this case, `processing_code` is the processsing code for the debit transaction, and `second_processing_code` is the processing code for the credit transaction.
    - `amount` number — Internal operation amount<br> `minimum: 0` `maximum: 18446744073709551617`
    - `validation_rules` ValidationRules — Rules that determine which validations are executed during the payment process.<br> Available validation rules: - `LEDGER` - `ACCOUNT_STATUS` - `FLEX_CONTROLS` - `RATES`<br> `force` is only supported for `LEDGER`. `override` is supported for `ACCOUNT_STATUS`, `FLEX_CONTROLS`, and `RATES`.
    - `created_at` string, datetime — Internal operation creation time. Format = yyyy-mm-dd:hr:mm:ss.
    - `metadata` InternalOperationMetadata — Key-value pairs containing data intended for storage in the Pismo system.<br> **Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis).

## Other responses

- `400` — A Bad Request validation error.
- `401` — Unauthorized operation.
- `403` — The request has been lost
- `409` — Conflict
- `423` — Locked
- `500` — Internal server error

---

[API](https://skmtc.net/pismo/apis/platform-authentication.md) · [All operations](https://skmtc.net/pismo/apis/platform-authentication/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pismo/platform-authentication/versions/935b62e16de4/schema)