Create withdrawal

POST /api/v2/household/{HouseholdGUID}/savings/{SavingsGUID}/withdrawals
Bearer auth

This endpoint allows users to create a new savings withdrawal.
When the parent savings has the DefaultAccount set to 1, you cannot create savings withdrawals.

Path parameters

  • HouseholdGUID string(uuid) Required

    The HouseholdGUID of the client.

  • SavingsGUID string(uuid) Required

    The SavingsGUID you want to create a withdrawal for.

application/json

Body Required

  • TransactionType integer Required

    If SavingsType is any of the following: 7, 8, 9, 10, 11, 12, 14, 17, 18, 19, or 21 then the allowed types are 6, and 7. Finally, if none of the above conditions are met then the only allowed type is 7.

  • TransactionAmount number(float) | null

    This field is required if the value of TransactionPercentage is not = 0. TransactionAmount must be greater than 0.

  • TransactionPercentage number(float) | null

    This field is required if the value of TransactionAmount is not = 0. TransactionPercentage must be greater than 0.

  • Frequency integer | null

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/withdrawals/options

  • StartBasis integer Required

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/withdrawals/options

  • StartEventGUID string(uuid) | null

    This field is required if the value of StartBasis = 4.

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/withdrawals/options

  • StartAge integer | null

    This field is required if the value of StartBasis = 2 or 7.

    Minimum value is 0, maximum value is 130.

  • StartDate string | null

    This field is required if the value of StartBasis = 3.

    Dates should be provided in the format "Y-m-d", where "Y" represents the year, "m" represents the month and "d" represents the day. For example, "2023-07-24" represents 24th July, 2023.

  • EndBasis integer | null

    This field is required if the value of Frequency is not = 120 and the value of TransactionType is not = 8.

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/withdrawals/options

  • EndEventGUID string(uuid) | null

    This field is required if the value of EndBasis = 4 and the value of Frequency is not = 120 and the value of TransactionType is not = 8. Event end must be after starting.

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/withdrawals/options

  • EndAge integer | null

    This field is required if the value of EndBasis = 2 or 7 and the value of Frequency is not = 120 and the value of TransactionType is not = 8. EndAge must be after starting.

    Minimum value is 0, maximum value is 130.

  • EndDate string | null

    This field is required if the value of EndBasis = 3 and the value of Frequency is not = 120 and the value of TransactionType is not = 8. EndDate must be after starting.

    Dates should be provided in the format "Y-m-d", where "Y" represents the year, "m" represents the month and "d" represents the day. For example, "2023-07-24" represents 24th July, 2023.

  • BackOfficeID string | null

    Maximum length is 255.

  • BackOfficeSync integer | null

    An integer representing the status of the back office sync:

    • 1: Yes
    • 2: No
    • 3: Only update from back office

Responses

POST /api/v2/household/{HouseholdGUID}/savings/{SavingsGUID}/withdrawals 
curl \
 -X POST https://api.fincalc.co.uk/api/v2/household/{HouseholdGUID}/savings/{SavingsGUID}/withdrawals \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"TransactionType":7,"TransactionAmount":100,"TransactionPercentage":12,"Frequency":52,"StartBasis":3,"StartEventGUID":"F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7","StartAge":42,"StartDate":"2024-01-01","EndBasis":3,"EndEventGUID":"F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7","EndAge":65,"EndDate":"2025-01-01","BackOfficeID":13573,"BackOfficeSync":1}'
Request examples 
{
  "TransactionType": 7,
  "TransactionAmount": 100,
  "TransactionPercentage": 12,
  "Frequency": 52,
  "StartBasis": 3,
  "StartEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
  "StartAge": 42,
  "StartDate": "2024-01-01",
  "EndBasis": 3,
  "EndEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
  "EndAge": 65,
  "EndDate": "2025-01-01",
  "BackOfficeID": 13573,
  "BackOfficeSync": 1
}
Response examples (201) 
{
  "success": true,
  "data": {
    "TransactionGUID": "61895427-011A-9214-B13E-FCE305CB4112",
    "TransactionType": 7,
    "SavingsGUID": "9DC78406-6FE4-3DE3-F3CF-0B8948F567E4",
    "TransactionAmount": 100,
    "TransactionPercentage": 12,
    "Frequency": 52,
    "StartBasis": 3,
    "StartEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
    "StartAge": 42,
    "StartDate": "2024-01-01",
    "EndBasis": 3,
    "EndEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
    "EndAge": 65,
    "EndDate": "2025-01-01",
    "BackOfficeID": "F7FBB6B1-2D90-485C-AE89-9F9FA0426F1E",
    "BackOfficeSync": 1,
    "FormattedValues": {
      "EndDate": "01/01/2025",
      "EndBasis": "Specific Age",
      "Frequency": "Paid Weekly",
      "StartBasis": "Current",
      "SavingsGUID": "API Test",
      "TransactionType": "Savings Income",
      "TransactionAmount": "£100",
      "TransactionPercentage": "12%"
    }
  }
}
Response examples (403) 
{
  "success": false,
  "message": "You do not have permission to edit the household."
}
Response examples (404) 
{
  "success": false,
  "message": "Household not found."
}
Response examples (422) 
{
  "success": false,
  "message": "Validation Error.",
  "data": {
    "ClientGUID": [
      "The client guid field is required."
    ]
  }
}
Response examples (500) 
{
  "success": false,
  "message": "Failed to create savings withdrawal in household"
}