# Create account balance history config v2

Create an account balance history configuration by division, organization, or program ID.

The configuration becomes effective on the day after the cycle closing time plus the cycle event delay.
Example:
  - Division timezone: `UTC`
  - Create account balance history configuration is called at: `2023-05-01T18:00:00Z`
  - Account balance history configuration `cycle_closing_time` is: `22:00:00`
  - Account balance history configuration `cycle_event_delay` is: `10`
  - Account balance history configuration starts at `2023-05-01T22:10:00Z`

This endpoint generates an [Account balance history configuration created](https://developers.pismo.io/events/docs/account-balances-balance-history-config-creation-1) event.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Banking - Transaction banking",
    "version": "0.9.0",
    "description": "Transaction banking API",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io",
      "description": "Sandbox API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Bank statements",
      "description": "Bank statements endpoints"
    }
  ],
  "components": {
    "schemas": {
      "AccountBalanceConfigTargetTypev2": {
        "type": "string",
        "description": "Account balance history config target type",
        "enum": [
          "ORGANIZATION",
          "PROGRAM",
          "DIVISION"
        ],
        "example": "DIVISION"
      },
      "BalanceHistoryConfigID": {
        "type": "string",
        "format": "uuid",
        "description": "Balance history configuration ID",
        "example": "550e8400-e29b-41d4-a716-446655440000"
      },
      "BalanceHistoryTargetType": {
        "type": "string",
        "description": "The target type of the balance history configuration, based on the hierarchical level it applies to.",
        "enum": [
          "ORGANIZATION",
          "PROGRAM",
          "DIVISION"
        ],
        "example": "ORGANIZATION"
      },
      "BalanceHistoryTargetID": {
        "type": "string",
        "description": "Target ID (`org_id`, `program_id`, or `division_id`)",
        "minLength": 1,
        "maxLength": 52,
        "example": "my-org-123"
      },
      "CreateAccountBalanceHistoryConfigurationRequestv2": {
        "description": "Create account balance history configuration request object.",
        "type": "object",
        "properties": {
          "target_type": {
            "$ref": "#/components/schemas/AccountBalanceConfigTargetTypev2"
          },
          "target_id": {
            "$ref": "#/components/schemas/TargetID"
          },
          "cycle_closing_time": {
            "$ref": "#/components/schemas/CycleClosingTimeV2"
          },
          "cycle_event_delay": {
            "$ref": "#/components/schemas/CycleEventDelay"
          }
        },
        "required": [
          "target_type",
          "target_id",
          "cycle_closing_time",
          "cycle_event_delay"
        ]
      },
      "CreateAccountBalanceHistoryConfigurationResponseV2": {
        "description": "Create account balance history configuration v2 response",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/BalanceHistoryConfigID"
          },
          "target_type": {
            "$ref": "#/components/schemas/BalanceHistoryTargetType"
          },
          "target_id": {
            "$ref": "#/components/schemas/BalanceHistoryTargetID"
          },
          "cycle_closing_time": {
            "$ref": "#/components/schemas/CycleClosingTime"
          },
          "cycle_event_delay": {
            "$ref": "#/components/schemas/CycleEventDelay"
          },
          "cycle_config_validity": {
            "$ref": "#/components/schemas/CycleConfigValidity"
          }
        }
      },
      "CycleClosingTime": {
        "type": "string",
        "format": "time",
        "description": "Time of day the cycle closes for a division. This time follows the timezone configured in division. You can find the division timezone using the [Get division by code](https://developers.pismo.io/pismo-docs/reference/get-division-by-code-v2) endpoint.",
        "pattern": "^(?:([01]?\\d|2[0-3]):([0-5]?\\d):)?([0-5]?\\d)$",
        "example": "22:00:00",
        "maxLength": 8
      },
      "CycleClosingTimeV2": {
        "type": "string",
        "format": "time",
        "description": "Cycle closing time indicates what time of day the cycle closes for a division, organization, or program. This time uses the timezone configured for the corresponding division, organization, or program.",
        "pattern": "^(?:([01]?\\d|2[0-3]):([0-5]?\\d):)?([0-5]?\\d)$",
        "example": "23:00:00",
        "maxLength": 8
      },
      "CycleConfigValidity": {
        "type": "object",
        "description": "The start and end date/time indicating when the cycle configuration becomes valid or invalid.\n",
        "properties": {
          "start": {
            "type": "string",
            "format": "datetime",
            "description": "The date and time when the configuration becomes valid. Format = `yyyy-mm-dd:hr:mm:ss`.",
            "example": "2023-04-01T22:10:00Z"
          },
          "end": {
            "type": "string",
            "format": "datetime",
            "description": "The date and time when the configuration ends. Format = `yyyy-mm-dd:hr:mm:ss`.",
            "example": "2023-05-01T22:10:00Z"
          }
        }
      },
      "CycleEventDelay": {
        "type": "integer",
        "format": "int32",
        "description": "The cycle event delay specifies how many minutes after `cycle_closing_time` the account balance history event is issued for each account in the division.",
        "example": 15,
        "minimum": 5
      },
      "ErrorCode": {
        "description": "Error code\n`minLength: 1`\n`maxLength: 12`\n",
        "type": "string",
        "minLength": 1,
        "maxLength": 12,
        "example": "WPMT0017"
      },
      "ErrorMessage": {
        "description": "Error message\n`minLength: 1`\n`maxLength: 1000`\n",
        "type": "string",
        "minLength": 1,
        "maxLength": 1000,
        "example": "Invalid JSON payload received: Error unmarshalling request"
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "message": {
            "$ref": "#/components/schemas/ErrorMessage"
          }
        }
      },
      "TargetID": {
        "type": "string",
        "description": "Target ID. When `target_type` is `DIVISION`, this value is the division code. Likewise, when `target_type` is `PROGRAM`, the value is the program ID, and so on.",
        "maxLength": 60,
        "example": "my-division-code"
      }
    },
    "responses": {
      "500InternalServer3": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "Generic internal error": {
                "value": {
                  "code": "CMN9999",
                  "message": "Internal error"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/bank-statements/v2/account-balances/history/config": {
      "post": {
        "summary": "Create account balance history config v2",
        "description": "Create an account balance history configuration by division, organization, or program ID.\n\nThe configuration becomes effective on the day after the cycle closing time plus the cycle event delay.\nExample:\n  - Division timezone: `UTC`\n  - Create account balance history configuration is called at: `2023-05-01T18:00:00Z`\n  - Account balance history configuration `cycle_closing_time` is: `22:00:00`\n  - Account balance history configuration `cycle_event_delay` is: `10`\n  - Account balance history configuration starts at `2023-05-01T22:10:00Z`\n\nThis endpoint generates an [Account balance history configuration created](https://developers.pismo.io/events/docs/account-balances-balance-history-config-creation-1) event.",
        "operationId": "post-account-balance-history-configv2",
        "tags": [
          "Bank statements"
        ],
        "requestBody": {
          "description": "Request body",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAccountBalanceHistoryConfigurationRequestv2"
              },
              "examples": {
                "Create account balance history config response": {
                  "value": {
                    "target_type": "ORGANIZATION",
                    "target_id": "TN-097d9c0e-0331-492a-93e2-95c8c2019fd1",
                    "division_code": "my-division",
                    "cycle_closing_time": "23:59:59",
                    "cycle_event_delay": 60
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateAccountBalanceHistoryConfigurationResponseV2"
                },
                "examples": {
                  "Created account balance history configuration successfully": {
                    "value": {
                      "id": "ee665f37-340f-461e-b520-af3b1b61c6ee",
                      "target_type": "PROGRAM",
                      "target_id": 42461,
                      "cycle_closing_time": "23:59:59",
                      "cycle_event_delay": 60,
                      "cycle_config_validity": {
                        "start": "2026-03-14T00:59:59-03:00"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Invalid JSON payload received": {
                    "value": {
                      "code": "WCFG0001",
                      "message": "Invalid JSON payload received: Error unmarshalling request"
                    }
                  },
                  "Missing required field": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "missing required field: {target_type} or {cycle_closing_time}"
                    }
                  },
                  "Invalid request": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "Request is invalid"
                    }
                  },
                  "division_code is a required field": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "division_code is a required field"
                    }
                  },
                  "division_code exceed size": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "division_code must be a maximum of 36 characters in length"
                    }
                  },
                  "cycle_closing_time is a required field": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "cycle_closing_time is a required field"
                    }
                  },
                  "cycle_closing_time exceed size": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "cycle_closing_time must be a maximum of 8 characters in length"
                    }
                  },
                  "cycle_closing_time invalid time format": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "cycle_closing_time has an invalid time format: {cycle_closing_time}"
                    }
                  },
                  "cycle_event_delay is a required field": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "cycle_event_delay is a required field"
                    }
                  },
                  "cycle_event_delay must be 5 minutes or greater": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "cycle_event_delay must be 5 or greater"
                    }
                  },
                  "cycle_event_delay exceed maximum minutes": {
                    "value": {
                      "code": "WCFG0002",
                      "message": "cycle_event_delay must be 1,439 or less"
                    }
                  },
                  "Invalid target type": {
                    "value": {
                      "code": "WCFG0010",
                      "message": "Invalid target type"
                    }
                  },
                  "Invalid target ID": {
                    "value": {
                      "code": "WCFG0011",
                      "message": "Invalid target ID"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Division not found": {
                    "value": {
                      "code": "WCFG0003",
                      "message": "Division not found"
                    }
                  },
                  "Program not found": {
                    "value": {
                      "code": "WCFG0006",
                      "message": "Program not found"
                    }
                  },
                  "Organization not found": {
                    "value": {
                      "code": "WCFG0007",
                      "message": "Organization not found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Division already configured": {
                    "value": {
                      "code": "WCFG0004",
                      "message": "Division is already configured"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500InternalServer3"
          }
        }
      }
    }
  }
}
```