# Create dormancy configuration
Create a dormancy configuration at the division or program level. This configuration sets the days of inactivity required for accounts to switch to a dormant status and the reason for the switch.
The dormancy configuration is applied to all accounts under the specified division or program.
Automated dormancy checks are performed according to the number of days specified in the dormancy configuration.
For information about dormancy, refer to [Dormancy overview](doc:dormancy-overview).
This endpoint generates a [Dormancy configuration created](https://developers.pismo.io/events/docs/corporate-dormancy-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": "Dormancy",
"description": "Dormancy endpoints"
}
],
"components": {
"schemas": {
"AccountStatus": {
"type": "string",
"minLength": 1,
"maxLength": 9,
"description": "Account status
\n`minLength: 1`\n`maxLength: 9`\n",
"example": "DORMANT"
},
"AccountStatusReasonID": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 4294967295,
"description": "Account status reason ID
\n`minimum: 1`\n`maximum: 4294967295`\n",
"example": 1438
},
"AccountStatusReasonExternalID": {
"type": "string",
"minLength": 1,
"maximum": 120,
"description": "External reason ID specifying account restrictions
\n`minimum: 1`\n`maximum: 120`\n",
"example": "CREDIT_ONLY"
},
"CheckTimezoneOrigin": {
"type": "string",
"description": "Specify whether the dormancy check uses the timezone of the account’s program or division. If not specified, the timezone of `target_id` is used.",
"enum": [
"PROGRAM",
"DIVISION"
],
"example": "PROGRAM"
},
"CreateDormancyConfigRequestv2": {
"description": "Create dormancy configuration response object",
"type": "object",
"properties": {
"check_time": {
"$ref": "#/components/schemas/DormancyCheckTime"
},
"target_type": {
"$ref": "#/components/schemas/DormancyTargetType"
},
"target_id": {
"$ref": "#/components/schemas/TargetID"
},
"statuses": {
"type": "array",
"description": "List of objects containing all the information pertinent to an organization's valid account status",
"items": {
"type": "object",
"properties": {
"status": {
"$ref": "#/components/schemas/AccountStatus"
},
"days": {
"$ref": "#/components/schemas/InactivityDays"
},
"reason_external_id": {
"$ref": "#/components/schemas/AccountStatusReasonExternalID"
},
"reactivation_with_last_restriction": {
"$ref": "#/components/schemas/ReactivationWithLastRestriction"
},
"restrictions": {
"$ref": "#/components/schemas/DormancyRestrictionsv2"
}
},
"required": [
"status",
"days",
"reason_external_id"
]
}
},
"dormant_processing_codes": {
"$ref": "#/components/schemas/DormantProcessingCodes"
},
"deny_forced_transaction_reactivation": {
"$ref": "#/components/schemas/DenyForcedTransactionReactivation"
},
"check_timezone_origin": {
"$ref": "#/components/schemas/CheckTimezoneOrigin"
},
"reactivation_exceptions_config": {
"$ref": "#/components/schemas/ReactivationExceptionsConfig"
}
},
"required": [
"check_time",
"target_type",
"target_id",
"statuses"
]
},
"CreateDormancyConfigResponse": {
"description": "Create dormancy configuration response object",
"type": "object",
"properties": {
"check_time": {
"$ref": "#/components/schemas/DormancyCheckTime"
},
"target_type": {
"$ref": "#/components/schemas/DormancyTargetType"
},
"target_id": {
"$ref": "#/components/schemas/TargetID"
},
"statuses": {
"type": "array",
"description": "List of objects containing all the information pertinent to an organization's valid account status",
"items": {
"type": "object",
"properties": {
"status": {
"$ref": "#/components/schemas/AccountStatus"
},
"days": {
"$ref": "#/components/schemas/InactivityDays"
},
"reactivation_with_last_restriction": {
"$ref": "#/components/schemas/ReactivationWithLastRestriction"
},
"reason_id": {
"$ref": "#/components/schemas/AccountStatusReasonID"
},
"reason_external_id": {
"$ref": "#/components/schemas/AccountStatusReasonExternalID"
},
"restrictions": {
"$ref": "#/components/schemas/DormancyRestrictions"
}
},
"required": [
"status",
"days",
"reason_id"
]
}
},
"dormancy_config_validity": {
"$ref": "#/components/schemas/DormancyConfigValidityWithoutEnd"
},
"dormant_processing_codes": {
"$ref": "#/components/schemas/DormantProcessingCodes"
},
"deny_forced_transaction_reactivation": {
"$ref": "#/components/schemas/DenyForcedTransactionReactivation"
},
"id": {
"$ref": "#/components/schemas/DormancyConfigID"
},
"check_timezone_origin": {
"$ref": "#/components/schemas/CheckTimezoneOrigin"
},
"reactivation_exceptions_config": {
"$ref": "#/components/schemas/ReactivationExceptionsConfig"
}
},
"required": [
"check_time",
"target_type",
"target_id",
"statuses",
"dormancy_config_validity"
]
},
"CurrentReasonExternalID": {
"type": "string",
"description": "The custom reason ID related to the `current_reason_id` specified in the dormancy restrictions.\nThe dormancy configuration checks to see whether the current `reason_external_id` matches the one in the configuration. If yes, the new `reason_external_id` is the `new_reason_external_id`.\n",
"example": "CREDIT_ONLY"
},
"CurrentReasonID": {
"type": "integer",
"description": "The dormancy configuration checks whether the current account `reason_id` is the same as the current account reason. If they are different, the dormancy configuration sets the reason to the value in the `reason_id` field.",
"example": 13
},
"DenyForcedTransactionReactivation": {
"type": "boolean",
"description": "Whether an account under that dormancy configuration should be reactivated when a forced transaction is made to that account (`true`) or not (`false`).",
"example": true,
"default": false
},
"DormancyCheckTime": {
"type": "string",
"format": "time",
"description": "Dormancy check time
\nNote: The timezone is inherited from the customer's divisions or programs.\n",
"pattern": "^(?:([01]?\\d|2[0-3]):([0-5]?\\d):)?([0-5]?\\d)$",
"example": "09:00:00",
"maxLength": 8
},
"DormancyConfigID": {
"type": "string",
"description": "Dormancy configuration ID generated internally",
"format": "uuid",
"example": "b993ba96-b3e8-4ef7-9cf7-7eee5ddafdab"
},
"DormancyConfigStartValid": {
"type": "string",
"description": "Date and time the dormancy configuration starts to be valid. Format = yyyy-mm-dd:hr:mm:ss.",
"example": "2024-10-18T17:45:26.930Z"
},
"DormancyConfigValidityWithoutEnd": {
"type": "object",
"description": "The datetimes for dormancy configuration validity",
"properties": {
"start": {
"$ref": "#/components/schemas/DormancyConfigStartValid"
}
}
},
"DormancyExceptionField": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Specifies which transaction attribute is checked in order to determine whether a transaction is exempt from reactivating a dormant account.",
"example": "soft_descriptor"
},
"DormancyExceptionValues": {
"type": "array",
"description": "Lists the values that, when present in the specified field, prevent the account from being reactivated by that transaction.",
"maxItems": 30,
"items": {
"$ref": "#/components/schemas/ValidExceptionValue"
}
},
"DormancyRestrictions": {
"type": "array",
"description": "List of objects that contains the information related to account dormancy restrictions.
\nIf there is a restriction in the list and the account's current reason is different from the value in `current_reason_id`, the dormancy configuration sets the reason to the value of the `reason_id` field. However, If the account's current reason is identical to the one in `current_reason_id`, the dormancy configuration sets the value to the `new_reason_id` field; in other words, the value in `new_reason_id` is the result of `reason_id` plus `current_reason_id`.\n",
"items": {
"type": "object",
"required": [
"current_reason_id",
"new_reason_id"
],
"properties": {
"current_reason_id": {
"$ref": "#/components/schemas/CurrentReasonID"
},
"new_reason_id": {
"$ref": "#/components/schemas/NewReasonID"
},
"current_reason_external_id": {
"$ref": "#/components/schemas/CurrentReasonExternalID"
},
"new_reason_external_id": {
"$ref": "#/components/schemas/NewReasonExternalID"
}
}
}
},
"DormancyRestrictionsv2": {
"type": "array",
"description": "Objects that contain the information related to account dormancy restrictions.\n",
"items": {
"type": "object",
"properties": {
"current_reason_external_id": {
"$ref": "#/components/schemas/CurrentReasonExternalID"
},
"new_reason_external_id": {
"$ref": "#/components/schemas/NewReasonExternalID"
}
}
}
},
"DormancyTargetType": {
"type": "string",
"description": "Dormancy configuration target",
"enum": [
"DIVISION",
"PROGRAM"
],
"example": "DIVISION"
},
"DormantProcessingCodes": {
"type": "array",
"description": "List of processing codes that prevent account reactivation. If there are financial transactions in an account that were made with any of these codes, the account cannot be reactivated.",
"items": {
"$ref": "#/components/schemas/ValidProcessingCode"
}
},
"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"
}
}
},
"InactivityDays": {
"type": "integer",
"format": "int32",
"description": "Days the account must be inactive before it is transitioned to the specified status.",
"example": 19
},
"NewReasonExternalID": {
"type": "string",
"description": "The custom reason ID related to the `new_reason_id` specified in the dormancy restrictions.\n",
"example": "DEBIT_ONLY"
},
"NewReasonID": {
"type": "integer",
"description": "This is the reason ID when the current account `reason_id` value is the same as `current_reason_id`.",
"example": 16
},
"ReactivationWithLastRestriction": {
"type": "boolean",
"description": "Whether the account should be reactivated to `normal` with its last manual change restriction (`true`) or not (`false`).",
"example": false
},
"ReactivationExceptionsConfig": {
"type": "object",
"description": "Specifies configuration rules that allow certain transactions to bypass dormancy reactivation based on defined transaction attributes and their corresponding values.",
"properties": {
"field": {
"$ref": "#/components/schemas/DormancyExceptionField"
},
"values": {
"$ref": "#/components/schemas/DormancyExceptionValues"
}
},
"required": [
"field",
"values"
]
},
"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"
},
"ValidExceptionValue": {
"type": "string",
"description": "Transaction attribute values that exempt the transaction from reactivating a dormant account",
"minLength": 1,
"maxLength": 100,
"example": "001"
},
"ValidProcessingCode": {
"type": "string",
"description": "Valid processing code used in transactions",
"minLength": 1,
"maxLength": 6,
"example": "220040"
}
},
"responses": {
"401Unauthorized": {
"description": "Access token is missing or invalid"
},
"403Forbidden": {
"description": "The request has been lost"
},
"500InternalServer": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Generic internal error": {
"value": {
"code": "ECMN9999",
"message": "Internal error"
}
}
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/corporate/v2/dormancy-config": {
"post": {
"summary": "Create dormancy configuration",
"description": "Create a dormancy configuration at the division or program level. This configuration sets the days of inactivity required for accounts to switch to a dormant status and the reason for the switch.\nThe dormancy configuration is applied to all accounts under the specified division or program.\nAutomated dormancy checks are performed according to the number of days specified in the dormancy configuration.\n\nFor information about dormancy, refer to [Dormancy overview](https://developers.pismo.io/pismo-docs/docs/dormancy-overview).\n\nThis endpoint generates a [Dormancy configuration created](https://developers.pismo.io/events/docs/corporate-dormancy-config-creation-1) event.\n",
"operationId": "post-dormancy-config-v2",
"parameters": [],
"tags": [
"Dormancy"
],
"requestBody": {
"description": "Create dormancy configuration request body",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDormancyConfigRequestv2"
},
"examples": {
"Example dormancy configuration structure": {
"value": {
"check_time": "22:00:00",
"target_type": "DIVISION",
"target_id": "abc-0001",
"statuses": [
{
"status": "INACTIVE",
"days": 60,
"reason_id": 1,
"reason_external_id": "01",
"restrictions": [
{
"current_reason_id": 13
},
{
"new_reason_id": 16
}
],
"reactivation_with_last_restriction": true
},
{
"status": "UNCLAIMED",
"days": 120,
"reason_id": 2,
"reason_external_id": "02",
"reactivation_with_last_restriction": false
},
{
"status": "DORMANT",
"days": 180,
"reason_id": 3,
"reason_external_id": "03",
"reactivation_with_last_restriction": false
}
],
"dormant_processing_codes": [
"100000",
"100001"
],
"deny_forced_transaction_reactivation": true,
"reactivation_exceptions_config": {
"field": "soft_descriptor",
"values": [
"001",
"002",
"003"
]
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDormancyConfigResponse"
},
"examples": {
"Dormancy configuration": {
"value": {
"id": "c49cf5f4-762a-429b-83cc-3a1bf2969e2e",
"check_time": "09:00:00",
"target_type": "DIVISION",
"target_id": "my-division-code",
"statuses": [
{
"status": "DORMANT",
"days": 1,
"reason_id": 1618,
"reason_external_id": "CREDIT_ONLY",
"restrictions": [
{
"current_reason_id": 1421,
"new_reason_id": 1618,
"current_reason_external_id": "DEBIT_ONLY",
"new_reason_external_id": "CREDIT_ONLY"
}
],
"reactivation_with_last_restriction": false
}
],
"dormant_processing_codes": [
"220040"
],
"dormancy_config_validity": {
"start": "2024-11-06T20:04:25.800Z"
},
"deny_forced_transaction_reactivation": false,
"check_timezone_origin": "PROGRAM",
"reactivation_exceptions_config": {
"field": "soft_descriptor",
"values": [
"001",
"002",
"003"
]
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Invalid JSON payload": {
"value": {
"code": "WDOR0001",
"message": "Invalid JSON payload received: Error unmarshalling request"
}
},
"check_time required": {
"value": {
"code": "WDOR0002",
"message": "check_time is a required field"
}
},
"check_time invalid format": {
"value": {
"code": "WDOR0002",
"message": "check_time has invalid format"
}
},
"target_type required": {
"value": {
"code": "WDOR0002",
"message": "target_type is a required field"
}
},
"target_type one of": {
"value": {
"code": "WDOR0002",
"message": "target_type must be one of [DIVISION PROGRAM]"
}
},
"target_id required": {
"value": {
"code": "WDOR0002",
"message": "target_id is a required field. If the target_type is DIVISION the target_id is the division code. If target_type is PROGRAM the target_id will be the program ID."
}
},
"statuses.status must be unique": {
"value": {
"code": "WDOR0002",
"message": "statuses.status must be unique in the statuses list"
}
},
"statuses.days must be unique": {
"value": {
"code": "WDOR0002",
"message": "statuses.days must be unique in the statuses list"
}
},
"statuses.days must be greater than 0": {
"value": {
"code": "WDOR0002",
"message": "statuses.days must be greater than 0"
}
},
"statuses should have at least 1 item": {
"value": {
"code": "WDOR0002",
"message": "statuses should have at least 1 item"
}
},
"dormant_processing_codes[i] must be at least 1 character in length": {
"value": {
"code": "WDOR0002",
"message": "dormant_processing_codes[i] must be at least 1 character in length"
}
},
"dormant_processing_codes[i] must be a maximum of 6 characters in length": {
"value": {
"code": "WDOR0002",
"message": "dormant_processing_codes[i] must be a maximum of 6 characters in length"
}
},
"dormant_processing_codes must contain only unique values": {
"value": {
"code": "WDOR0002",
"message": "dormant_processing_codes must contain only unique values"
}
},
"Invalid restrictions.current_reason_external_id field": {
"value": {
"code": "WDOR0010",
"message": "Invalid current_reason_external_id, the current_reason_external_id you entered does not exist."
}
},
"Invalid Restrictions.new_reason_external_id field": {
"value": {
"code": "WDOR0011",
"message": "Invalid new_reason_external_id, the new_reason_external_id you entered does not exist."
}
},
"statuses.status invalid status": {
"value": {
"code": "WDOR0005",
"message": "Invalid status {status}"
}
},
"statuses.reason_external_id invalid reason": {
"value": {
"code": "WDOR0006",
"message": "Invalid reason_external_id {reason_id}"
}
},
"Dormancy configuration already exists": {
"value": {
"code": "WDOR0008",
"message": "Dormancy configuration with ID {dormancyID} already exists"
}
},
"Invalid dormant processing code": {
"value": {
"code": "WDOR0009",
"message": "Invalid dormant processing code [{dormant_processing_code}]"
}
},
"Invalid timezone origin": {
"value": {
"code": "WDOR0002",
"message": "check_timezone_origin must be one of [DIVISION PROGRAM]"
}
},
"Invalid statuses.days": {
"value": {
"code": "WDOR0002",
"message": "statuses.days must be less than or equal to 2147483647"
}
},
"Invalid restrictions.current_reason_external_id": {
"value": {
"code": "WDOR0002",
"message": "statuses.restrictions.current_reason_external_id must be unique in the restrictions list"
}
},
"reactivation_exceptions_config.field must be soft_descriptor or metadata.*": {
"value": {
"code": "WDOR0002",
"message": "reactivation_exceptions_config.field must be soft_descriptor or metadata.*"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"program not found": {
"value": {
"code": "WDOR0004",
"message": "Program with program_id {targetID} not found"
}
},
"division not found": {
"value": {
"code": "WDOR0003",
"message": "Division with division_code {targetID} not found"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
}
}
}
}
```