---
title: "Add Purse – Creates a new savings purse for an account."
method: POST
path: "/programs/{programCode}/accounts/{accountIdentifier}/purses"
tags: ["Purse"]
---

# Add Purse – Creates a new savings purse for an account.

`POST /programs/{programCode}/accounts/{accountIdentifier}/purses`

Creates a new savings purse for an account. Only allowed if the account status is normal. Interest Rate Tier information is included if provided. Returns the created purse details.

## Path parameters

- `accountIdentifier` string, required
- `programCode` string, required

## Headers

- `X-GD-RequestId` string, required

## Request body

- CreatePurseRequest — Represents a request to create a new purse for an account. Used to specify purse type, description, goal, interest rate, and sub-type.
  - `purseType` string, nullable — The type of purse to create (e.g., "Savings", "General").
  - `purseDescription` string, nullable — The description of the purse.
  - `goalAmount` number, double, nullable — The goal amount for the purse, if applicable.
  - `goalDate` string, nullable — The goal date for the purse, if applicable (YYYY-MM-DD).
  - `iconName` string, nullable — The icon name for the purse.
  - `interestRateTier` string, nullable — The interest rate tier for the purse, if applicable.
  - `interestYieldStartDate` string, nullable — The start date for interest yield (YYYY-MM-DD).
  - `autoAlignStartDate` boolean — Indicates whether to auto-align the start date for interest calculation.
  - `purseSubType` string, nullable — The sub-type of the purse (e.g., "General", "Taxes", "Goal").

## Response `200`

OK

- CreatePurseResponse — Represents the response returned after creating a new purse. Contains the created purse details.
  - `purse` Purse — Represents a purse (sub-account or balance container) associated with a user's account. Contains identifiers, type, balances, status, goal information, interest details, and display attributes. Used to provide detailed information about each purse, including available and ledger balances, status, and configuration for savings, spending, or other financial goals.
    - `purseIdentifier` string, nullable — The unique identifier for the purse.
    - `purseType` string, nullable — The type of purse (e.g., "Savings", "Spending", "Goal").
    - `purseDescription` string, nullable — A human-readable description of the purse.
    - `availableBalance` number, double — The available balance in the purse, representing funds that can be spent or withdrawn.
    - `ledgerBalance` number, double — The ledger balance in the purse, representing the total balance including pending transactions.
    - `availableBalanceAsOfDateTime` string, nullable — The date and time when the available balance was last updated.
    - `ledgerBalanceAsOfDateTime` string, nullable — The date and time when the ledger balance was last updated.
    - `isHidden` boolean — Indicates whether the purse is hidden from the user interface.
    - `status` string, nullable — The current status of the purse.
    - `goalAmount` number, double, nullable — The goal amount set for the purse, if applicable (e.g., for savings goals).
    - `goalDate` string, nullable — The target date for achieving the goal amount.
    - `iconName` string, nullable — The name of the icon associated with the purse for display purposes.
    - `createDate` string, date-time, nullable — The date and time when the purse was created.
    - `changeDate` string, date-time, nullable — The date and time when the purse was last changed or updated.
    - `purseNumber` string, nullable — The purse number, which may be used for display or reference purposes.
    - `interestRateTierIdentifier` string, nullable — The identifier for the interest rate tier applied to the purse, if applicable.
    - `interestRateTier` string, nullable — The name or description of the interest rate tier applied to the purse.
    - `interestYieldStartDate` string, nullable — The start date for interest yield calculation.
    - `interestYieldEndDate` string, nullable — The end date for interest yield calculation.
    - `APY` number, double, nullable — The annual percentage yield (APY) for the purse, if applicable.
    - `purseSubType` string, nullable — The subtype of the purse, providing additional categorization (e.g., "RoundUp", "EmergencyFund").
    - `interestRate` number, double, nullable — The interest rate applied to the purse, if applicable.
    - `isRoundUp` boolean — Indicates whether the purse is configured for round-up savings functionality.
  - `responseDetails` ResponseDetail[], nullable — Required: A list of response details providing status codes, descriptions, and additional information about the result of the operation.
    - `code` integer — The primary status or error code for the response (e.g., 200 for success, 400 for validation error).
    - `subCode` integer, nullable — An optional subcode providing more granular detail about the response or error.
    - `description` string, nullable — A human-readable description of the response, error, or status.
    - `url` string, nullable — A URL linking to documentation or a web page with more information about the response code.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/greendot/apis/baas-apis.md) · [All operations](https://skmtc.net/greendot/apis/baas-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greendot/baas-apis/revisions/666553766b78/schema)