---
updatedAt: 2026-04-22T18:05:56.000Z
---
Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# Attach deposit to account
Attach a time deposit product to an account.
This endpoint generates the [Account attached](https://developers.pismo.io/events/docs/deposit-product-account-attach-1) event.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Banking - Interest-bearing accounts",
"version": "1.0.0",
"description": "API for interest-bearing account functionality",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/savings-products",
"description": "Sandbox API server for testing"
}
],
"tags": [
{
"name": "Account attachment",
"description": "Endpoints that manage account attachments to interest-bearing account products"
}
],
"components": {
"parameters": {
"accountId": {
"description": "Account ID",
"in": "path",
"name": "accountId",
"required": true,
"schema": {
"type": "integer"
},
"example": 123456
}
},
"schemas": {
"ErrorResponse": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error type code",
"example": "EIBACC0003"
},
"details": {
"type": "string",
"description": "Error details",
"example": "error EIBACC0008: Validation error [(Field 'Order' is invalid)]"
},
"message": {
"description": "Error message",
"example": "Bad Request",
"type": "string"
}
}
},
"PayoutAccount": {
"type": "object",
"description": "The payout account defines where outbound payments are sent, and it is used in two operational contexts.
\n\n* **Capitalization flow**: When the capitalization mode is set to `PAYOUT`, the capitalized interest is directed to this account. If the mode is `REINVEST`, the payout account is not involved because the interest is added to the principal instead.\n* **Maturity instruction flow**: At maturity, this account receives principal or interest whenever the maturity instructions specify `PAY` for either `maturity_instructions.principal` or `maturity_instructions.interest`. This flow always relies on the payout account, regardless of how capitalization is configured.\n\nBoth flows reference the same payout account settings. Choosing `REINVEST` for capitalization does not remove or disable the payout account, and it remains fully available for maturity‑related payments.\n",
"properties": {
"label": {
"type": "string",
"description": "Label to identify the account\n",
"example": "My payout account"
},
"type": {
"type": "string",
"description": "Payout account type, either `INTERNAL` or `EXTERNAL`\n",
"enum": [
"INTERNAL",
"EXTERNAL"
],
"example": "INTERNAL"
},
"internal_account_id": {
"type": "number",
"description": "Internal account ID for the account that receives the payments.\nRequired for type `INTERNAL` and not allowed for `EXTERNAL`.\n",
"example": 123456
},
"external_account": {
"type": "object",
"description": "Contains user-defined key-value pairs that identify the external account receiving the payments.\nNote that external account information is client-provided.\n\nRequired for type `EXTERNAL` and not allowed for `INTERNAL`.\n",
"example": {
"key": "value"
}
}
}
},
"MaturityPeriod": {
"type": "object",
"description": "Defines when the deposit matures. There are three usage modes:\n\n* **Relative period**: Sends `unit` + `value` (e.g. `MONTHS` + `6`).\n* **Explicit date**: Sends `calendar_maturity_date` (e.g. `2027-06-15`).\n* **Default**: Omits the field or sends `{}`. The product's configured default maturity term (`PRODUCT_DEFAULT_MATURITY_DATE_DAYS`, typically `10950` days ≈ 30 years) is applied.\n\n**NOTE**: `calendar_maturity_date` and `unit`/`value` are mutually exclusive, sending both in the same request returns a `400` validation error.\n\nIn the **attach** endpoints, the response returns exactly what was sent in the request:\n* Send `unit` + `value` returns `unit` + `value`\n* Send `calendar_maturity_date` returns `calendar_maturity_date`\n* Send nothing (default fallback applied) returns `unit=DAYS` and `value` equal to the product's configured `PRODUCT_DEFAULT_MATURITY_DATE_DAYS`\n\n**NOTE**: this behavior applies only to attach. The `GET` attachment endpoints and `PATCH /v1/deposits/accounts/{accountId}/attachment` return the resolved term, with `unit`, `value`, and `calendar_maturity_date` populated together. A `PATCH` sent in explicit‑date form is returned normalized as `{unit: DAYS, value: , calendar_maturity_date: }`.\n",
"properties": {
"unit": {
"$ref": "#/components/schemas/MaturityPeriodUnit"
},
"value": {
"$ref": "#/components/schemas/MaturityPeriodValue"
},
"calendar_maturity_date": {
"$ref": "#/components/schemas/CalendarMaturityDate"
}
}
},
"MaturityPeriodUnit": {
"type": "string",
"description": "Time unit for the relative maturity period. It's used together with `value` and cannot coincide with `calendar_maturity_date`.\n\n- `DAYS`: Uses `value` directly. Example: `value=90` → 90 days.\n- `WEEKS`: Multiplies `value` by 7. Example: `value=4` → 28 days.\n- `MONTHS`: Calculates calendar-month with end-of-month (EOM) clamping when the target day does not exist. Example: `2024-01-31` + 1 month = `2024-02-29` (leap year) or `2025-02-28` (non-leap year).\n- `YEARS`: Calculates calendar-year, for example: `2024-02-29` + 1 year = `2025-02-28`. Note that there is no Feb 29 in 2025.\n\nFor `WEEKS`, `MONTHS`, and `YEARS`, the resulting calendar date is converted back to a day count to validate against the product's configured minimum or maximum term.\n",
"enum": [
"DAYS",
"WEEKS",
"MONTHS",
"YEARS"
],
"example": "MONTHS"
},
"MaturityPeriodValue": {
"type": "integer",
"description": "Number of time units until maturity. Must be greater than `0`. Mutually exclusive with `calendar_maturity_date`.\n",
"minimum": 1,
"example": 6
},
"CalendarMaturityDate": {
"type": "string",
"format": "date",
"description": "Maturity date. Format is `YYYY-MM-DD`. The date must be a future date.\n\nThis date cannot coincide with `unit`/`value`, sending both in the same request returns a `400` validation error.\n",
"example": "2027-06-15"
},
"DepositConfigs": {
"type": "object",
"properties": {
"maturity_period": {
"$ref": "#/components/schemas/MaturityPeriod"
},
"payout_account": {
"$ref": "#/components/schemas/PayoutAccount"
},
"interest_capitalization_mode": {
"type": "string",
"enum": [
"REINVEST",
"PAYOUT"
],
"default": "REINVEST",
"description": "Controls the treatment of capitalized interest. Optional field.
\n\n* `REINVEST` (default): The Pismo platform adds the capitalized amount to the principal through the interest engine. The new principal becomes the foundation for the next accrual cycle. No `payout_account` is required.\n* `PAYOUT` (explicit): The capitalized amount is routed to `payout_account`. A valid `payout_account` is **required** in this request when this value is passed explicitly—omitting it returns `400 EIBACC0379`.\n* `Omitted`: The Pismo platform applies `REINVEST`. Both the GET operation and events return `REINVEST`.\n\nThis setting affects only the capitalization process. The maturity instruction flow always uses `payout_account`, regardless of the value of this field.\n",
"example": "REINVEST"
},
"overrides": {
"$ref": "#/components/schemas/AttachmentOverridesRequest"
}
}
},
"AttachmentOverridesRequest": {
"type": "object",
"description": "Per-attachment overrides applied on top of the product defaults. All sub-fields are optional.\nThis object contains the per‑attachment overrides that supplement the product defaults. All sub‑fields are optional. Omitting a section causes the Pismo platform to follow the normal fallback sequence, moving from the account level to the program and then to the product defaults. Each penalty type provides `waived` as a required field, optional type‑specific fields, and an optional `valid_until` to schedule the revert.\n",
"properties": {
"maturity_instructions": {
"$ref": "#/components/schemas/MaturityInstructionsOverrideRequest"
},
"renewal_term": {
"$ref": "#/components/schemas/RenewalTermOverrideRequest"
},
"penalties": {
"$ref": "#/components/schemas/PenaltiesOverrideRequest"
}
}
},
"MaturityInstructionsOverrideRequest": {
"type": "object",
"description": "Overrides the deposit’s behavior at maturity. If a field is omitted, the Pismo platform uses the value defined at the higher‑level configuration that governs this deposit.\n",
"properties": {
"principal": {
"type": "string",
"enum": [
"ROLLOVER",
"PAY"
],
"description": "Specifies how the principal is handled once the deposit matures.",
"example": "ROLLOVER"
},
"interest": {
"type": "string",
"enum": [
"ROLLOVER",
"PAY"
],
"description": "Specifies how the interest is handled once the deposit matures.",
"example": "PAY"
},
"reason": {
"type": "string",
"maxLength": 100,
"description": "Optional audit-trail reason.",
"example": "Customer preference at onboarding"
}
}
},
"RenewalTermOverrideRequest": {
"type": "object",
"description": "Specifies the recurring rollover term, not to be confused with the initial `maturity_period`.\n\nYou must provide either `unit` with `value` or `renewal_calendar_maturity_date`.\n\nA `ROLLOVER` configuration in principal or interest is required.\n\nWhen you pass `renewal_calendar_maturity_date`, the Pismo platform converts the interval from today into a day count and stores it at attach time in normalized form: `{unit: DAYS, value: }`.\n",
"properties": {
"unit": {
"type": "string",
"enum": [
"DAYS",
"WEEKS",
"MONTHS",
"YEARS"
],
"description": "Time unit of the renewal term. Required together with `value` when calendar form is not used.",
"example": "MONTHS"
},
"value": {
"type": "integer",
"minimum": 1,
"description": "Number of units. Required together with `unit` when calendar form is not used.",
"example": 6
},
"renewal_calendar_maturity_date": {
"type": "string",
"format": "date",
"description": "Explicit calendar date (`YYYY-MM-DD`), the date must be a future date, and does not coincide with `unit`+`value`.",
"example": "2027-05-22"
}
}
},
"PenaltiesOverrideRequest": {
"type": "object",
"description": "Per-type penalty overrides. Each type independently uses three-state semantics:\nomit (inherit) · `{waived: true}` (exempt) · `{waived: false, }` (customize).\n",
"properties": {
"reason": {
"type": "string",
"maxLength": 100,
"description": "Optional audit-trail reason for the entire penalties block.",
"example": "Q4 2026 VIP retention package"
},
"grace_period": {
"$ref": "#/components/schemas/GracePeriodOverrideRequest"
},
"early_withdrawal_after_opening": {
"$ref": "#/components/schemas/EarlyWithdrawalAfterOpeningOverrideRequest"
},
"withdrawal_fee": {
"$ref": "#/components/schemas/WithdrawalFeeOverrideRequest"
},
"tiered_interest_forfeiture": {
"$ref": "#/components/schemas/TieredInterestForfeitureOverrideRequest"
},
"subsequent_withdrawals": {
"$ref": "#/components/schemas/SubsequentWithdrawalsOverrideRequest"
}
}
},
"GracePeriodOverrideRequest": {
"type": "object",
"description": "Grace period override. Type-specific fields are optional pointers, when omitted, the Pismo platform follows the normal fallback sequence, moving from the account level to the program and then to the product defaults.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean",
"description": "`true` = fully exempt; `false` = penalty active (customize via the fields below)."
},
"duration_days": {
"type": "integer",
"minimum": 0
},
"penalty_interest_days": {
"type": "integer",
"minimum": 0
},
"valid_until": {
"type": "string",
"format": "date-time",
"description": "Schedules the revert of this override via EventBridge. This value must be a future date and follows the ISO 8601 standard."
}
}
},
"EarlyWithdrawalAfterOpeningOverrideRequest": {
"type": "object",
"description": "Override for early withdrawal after account opening.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean"
},
"applicable_within_days": {
"type": "integer",
"minimum": 0
},
"penalty_interest_days": {
"type": "integer",
"minimum": 0
},
"valid_until": {
"type": "string",
"format": "date-time"
}
}
},
"WithdrawalFeeOverrideRequest": {
"type": "object",
"description": "Withdrawal fee override.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean"
},
"type": {
"type": "string",
"enum": [
"PERCENTAGE",
"FIXED"
]
},
"value": {
"type": "number",
"exclusiveMinimum": 0
},
"valid_until": {
"type": "string",
"format": "date-time"
}
}
},
"TieredInterestForfeitureOverrideRequest": {
"type": "object",
"description": "Tiered interest forfeiture override. Tiers replace the product's tiers when provided.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean"
},
"tiers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TieredInterestForfeitureTierRequest"
}
},
"valid_until": {
"type": "string",
"format": "date-time"
}
}
},
"TieredInterestForfeitureTierRequest": {
"type": "object",
"required": [
"min_days_held",
"forfeited_interest_days"
],
"properties": {
"min_days_held": {
"type": "integer",
"minimum": 0
},
"max_days_held": {
"type": "integer",
"minimum": 0,
"description": "Optional. Open-ended tier when omitted."
},
"forfeited_interest_days": {
"type": "integer",
"minimum": 0
}
}
},
"SubsequentWithdrawalsOverrideRequest": {
"type": "object",
"description": "Subsequent withdrawals (Regulation D) override.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean"
},
"applicable_within_days": {
"type": "integer",
"minimum": 1
},
"penalty_interest_days": {
"type": "integer",
"minimum": 1
},
"window_behavior": {
"type": "string",
"enum": [
"ROLLING",
"FIXED"
]
},
"valid_until": {
"type": "string",
"format": "date-time"
}
}
},
"DepositAttachAccountResponse": {
"type": "object",
"description": "Response body returned when attaching a deposit product to an account",
"properties": {
"account_id": {
"type": "integer",
"description": "Account ID",
"example": 123456
},
"product_id": {
"type": "string",
"description": "Product ID",
"example": "2c336e9d-d04f-4fd0-8f6e-25808f48d70c"
},
"external_account_id": {
"type": "string",
"description": "External account identifier of the account. Returned only when the account has an external account identifier.",
"example": "ext-acc-001"
},
"effective_date": {
"type": "string",
"format": "date",
"description": "The effective value date of the attachment. Format is `YYYY-MM-DD`.\nThis is the date when the attachment becomes valid. Maturity is calculated from this date.\n",
"example": "2025-12-01"
},
"deposit_configs": {
"type": "object",
"properties": {
"maturity_period": {
"$ref": "#/components/schemas/MaturityPeriod"
},
"interest_capitalization_mode": {
"type": "string",
"enum": [
"PAYOUT",
"REINVEST"
],
"description": "Present only when the request included `interest_capitalization_mode`. Reflects the value stored on the attachment.\n",
"example": "REINVEST"
},
"accrual_model": {
"type": "string",
"description": "Accrual model inherited from the attached product. `DEPOSIT_BASIS` or `BALANCE_BASIS`.",
"enum": [
"DEPOSIT_BASIS",
"BALANCE_BASIS"
],
"default": "DEPOSIT_BASIS",
"example": "DEPOSIT_BASIS"
},
"balance_type": {
"type": "string",
"description": "Balance type inherited from the attached product. Only meaningful when `accrual_model` is `BALANCE_BASIS`.",
"enum": [
"VALUE_DATED_BALANCE",
"LEDGER_BALANCE"
],
"default": "VALUE_DATED_BALANCE",
"example": "VALUE_DATED_BALANCE"
},
"overrides": {
"$ref": "#/components/schemas/AttachmentOverridesSnapshot"
}
}
}
}
},
"AttachmentOverridesSnapshot": {
"type": "object",
"description": "Representation of the persisted overrides, present only when the request defined at least one override. Sub-fields are included only when set. The `renewal_term` retains the structure provided by the client (calendar form or `unit`+`value`), mirroring the behavior of `maturity_period`.\n",
"properties": {
"maturity_instructions": {
"$ref": "#/components/schemas/MaturityInstructionsOverrideRequest"
},
"renewal_term": {
"$ref": "#/components/schemas/RenewalTermResponse"
},
"penalties": {
"$ref": "#/components/schemas/PenaltiesOverrideSnapshot"
}
}
},
"RenewalTermResponse": {
"type": "object",
"description": "Renewal term applied on each rollover. The platform preserves the client’s original format: `unit`+`value` appears when provided, and `renewal_calendar_maturity_date` is returned as a string when that form is used.\n",
"properties": {
"unit": {
"type": "string",
"enum": [
"DAYS",
"WEEKS",
"MONTHS",
"YEARS"
],
"example": "MONTHS"
},
"value": {
"type": "integer",
"minimum": 1,
"example": 6
},
"renewal_calendar_maturity_date": {
"type": "string",
"format": "date",
"description": "Returned only when the request uses the calendar format. Format = `YYYY-MM-DD`.",
"example": "2027-05-22"
}
}
},
"PenaltiesOverrideSnapshot": {
"type": "object",
"description": "Persisted penalty overrides for each type. Types appear only when set. Each entry includes `waived`, the relevant type-specific fields, and an optional `valid_until` for scheduling the revert.\n",
"properties": {
"reason": {
"type": "string",
"example": "Q4 2026 VIP retention package"
},
"grace_period": {
"$ref": "#/components/schemas/GracePeriodOverrideRequest"
},
"early_withdrawal_after_opening": {
"$ref": "#/components/schemas/EarlyWithdrawalAfterOpeningOverrideRequest"
},
"withdrawal_fee": {
"$ref": "#/components/schemas/WithdrawalFeeOverrideRequest"
},
"tiered_interest_forfeiture": {
"$ref": "#/components/schemas/TieredInterestForfeitureOverrideRequest"
},
"subsequent_withdrawals": {
"$ref": "#/components/schemas/SubsequentWithdrawalsOverrideRequest"
}
}
},
"DepositAttachRequest": {
"type": "object",
"required": [
"product_id"
],
"properties": {
"product_id": {
"type": "string",
"description": "Product identifier.",
"example": "2c336e9d-d04f-4fd0-8f6e-25808f48d70c"
},
"effective_date": {
"type": "string",
"format": "date",
"description": "Backdated effective date for the attachment in `YYYY-MM-DD` format. This is the date starting from which the attachment is considered valid.\n- If omitted, it defaults to the current date\n- Must be less than or equal to the current date (cannot be in the future)\n- Cannot be more than `ATTACHMENT_MAX_BACKDATING_DAYS` (default: 90 days) in the past\n- Maturity date is calculated from this date, not from the date when you call the API.\n- No retroactive interest accrual, capitalization, or postings are triggered\n",
"example": "2025-12-01"
},
"deposit_configs": {
"$ref": "#/components/schemas/DepositConfigs"
},
"metadata": {
"type": "object",
"description": "The metadata object contains user-defined key-value pairs that provide additional context or custom information.
\nThe platform has no control over its content, but rather controlled by the user.
\n\n**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#metadata).\n",
"example": {
"key": "value"
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"responses": {
"404NotFound": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
},
"examples": {
"invalidRequestBody": {
"summary": "Bad Request",
"value": {
"code": "EIBACC0064",
"message": "Product not found"
}
}
}
}
}
},
"409Conflict": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
},
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"code": "EIBACC0114",
"message": "Product is already detached"
}
}
}
}
}
}
}
},
"paths": {
"/v1/deposits/accounts/{accountId}/attach": {
"post": {
"tags": [
"Account attachment"
],
"summary": "Attach deposit to account",
"description": "Attach a time deposit product to an account.\nThis endpoint generates the [Account attached](https://developers.pismo.io/events/docs/deposit-product-account-attach-1) event.\n",
"operationId": "interest-bearing-v1-deposit-attach-account",
"parameters": [
{
"$ref": "#/components/parameters/accountId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DepositAttachRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DepositAttachAccountResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
},
"examples": {
"validationError": {
"summary": "Generic validation error",
"value": {
"code": "EIBACC0008",
"message": "Bad Request"
}
},
"overrideValidUntilPast": {
"summary": "valid_until must be a future datetime",
"value": {
"code": "EIBACC0308",
"message": "valid_until must be a future datetime"
}
},
"renewalTermMutuallyExclusive": {
"summary": "renewal_term — calendar date and unit/value are mutually exclusive",
"value": {
"code": "EIBACC0309",
"message": "Validation error",
"details": "renewal_term accepts either renewal_calendar_maturity_date OR unit+value, not both."
}
},
"renewalTermRequiresRollover": {
"summary": "renewal_term requires ROLLOVER in maturity_instructions",
"value": {
"code": "EIBACC0310",
"message": "Validation error",
"details": "renewal_term requires ROLLOVER configured in maturity_instructions.principal or maturity_instructions.interest (account/program override or product default)."
}
},
"renewalCalendarMaturityDateNotFuture": {
"summary": "renewal_calendar_maturity_date must be a future date",
"value": {
"code": "EIBACC0311",
"message": "Validation error",
"details": "renewal_calendar_maturity_date must be a future date (after today)"
}
},
"renewalTermFieldsMissing": {
"summary": "renewal_term requires unit+value or renewal_calendar_maturity_date",
"value": {
"code": "EIBACC0312",
"message": "Validation error",
"details": "renewal_term requires either both unit and value, or renewal_calendar_maturity_date"
}
},
"capitalizationPayoutRequiresPayoutAccount": {
"summary": "interest_capitalization_mode PAYOUT requires a payout_account",
"value": {
"code": "EIBACC0379",
"message": "interest_capitalization_mode PAYOUT requires a fully resolved payout_account",
"details": "payout_account is required when interest_capitalization_mode is PAYOUT."
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/404NotFound"
},
"409": {
"$ref": "#/components/responses/409Conflict"
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
},
"examples": {
"internalError": {
"summary": "Internal error",
"value": {
"code": "EIBACC0007",
"message": "Internal error"
}
},
"penaltyOverrideScheduleError": {
"summary": "Failed to schedule override expiration",
"value": {
"code": "EIBACC0304",
"message": "Failed to schedule override expiration"
}
}
}
}
}
}
}
}
}
},
"security": [
{
"BearerAuth": []
}
]
}
```