Create withdrawal

POST /api/v2/household/{HouseholdGUID}/pensions/{PensionGUID}/withdrawals
Bearer auth

This endpoint allows users to create a new pension withdrawal.

Path parameters

  • HouseholdGUID string(uuid) Required

    The HouseholdGUID of the client.

  • PensionGUID string(uuid) Required

    The PensionGUID you want to create a withdrawal for. Should only be linked to PensionGUID which has PensionType = 3.

application/json

Body Required

  • TransactionType integer Required

    TransactionType must be 5.

    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}/pensions/contributions/options

  • WithdrawalStyle 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}/pensions/contributions/options

  • TFCBasis integer | null

    This field is required if the value of WithdrawalStyle = 1, 2, 3, 5 or 7.

    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}/pensions/contributions/options

  • FundBasis integer | null

    This field is required if the value of WithdrawalStyle = 2 or 5.

    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}/pensions/contributions/options

  • FundAmount number(float) | null

    This field is required if the value of FundBasis = 2 or the value of WithdrawalStyle = 7. The value must be greater than or equal to 0.

  • FundPercentage number(float) | null

    This field is required if the value of FundBasis = 3. The value must be greater than or equal to 0.

  • IncomeRate number(float) | null

    This field is required if the value of WithdrawalStyle = 5. The value must be greater than or equal to 0.

  • IncomePreference integer | null

    This field is required if the value of WithdrawalStyle = 5.

    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}/pensions/contributions/options

  • TFCAmount number(float) | null

    This field is required if the value of TFCBasis = 3. The value must be greater than or equal to 0.

  • TFCPercentage number(float) | null

    This field is required if the value of TFCBasis = 4. The value must be greater than or equal to 0.

  • AnnuityRate number(float) | null

    This field is required if the value of WithdrawalStyle = 2. The value can be a negative number.

  • TransactionAmount number(float) | null

    This field is required if the value of WithdrawalStyle = 7 or WithdrawalStyle = 3, 4 or 6 and the value of TransactionPercentage = 0. The value must be greater than or equal to 0.

  • TransactionPercentage number(float) | null

    This field is required if the value of WithdrawalStyle = 3, 4 or 6 and the value of TransactionAmount = 0. The value must be greater than or equal to 0.

  • Frequency integer Required

    This field is required if the value of WithdrawalStyle is not = 5. When the value of WithdrawalStyle = 1, Frequency must be 120.

    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

  • WithdrawalPreference integer | null

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

    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}/pensions/contributions/options

  • GuaranteePeriod integer | null

    This field is required if the value of WithdrawalStyle = 2.

    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}/pensions/contributions/options

  • SpousePension number(float) | null

    This field is required if the value of WithdrawalStyle = 2. The value must be greater than or equal to 0.

  • MaturityAmount number(float) | null

    This field is required if the value of WithdrawalStyle = 7. The value must be greater than or equal to 0.

  • AnnuityEscalationBasis integer | null

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

    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}/pensions/contributions/options

  • AnnuityEscalationPercentage number(float) | null

    This field is required if the value of WithdrawalStyle = 2 or 7 and the value of AnnuityEscalationBasis = 3.
    The value must be greater than or equal to 0.

  • 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. The value of StartAge must be in the future.

    Minimum value is 0, maximum value is 130.

  • StartDate string | null

    This field is required if the value of StartBasis = 3. The value of StartDate must be in the future.

    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 WithdrawalStyle is not = 1, 2, 5 or 7.

    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 WithdrawalStyle is not = 1, 2, 5 or 7. 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 WithdrawalStyle is not = 1, 2, 5 or 7. 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 WithdrawalStyle is not = 1, 2, 5 or 7. 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.

  • Term integer | null

    This field is required if the value of WithdrawalStyle = 7.

  • 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}/pensions/{PensionGUID}/withdrawals 
curl \
 -X POST https://api.fincalc.co.uk/api/v2/household/{HouseholdGUID}/pensions/{PensionGUID}/withdrawals \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"TransactionType":5,"WithdrawalStyle":2,"TFCBasis":2,"FundBasis":1,"FundAmount":100,"FundPercentage":12,"IncomeRate":12,"IncomePreference":1,"TFCAmount":100,"TFCPercentage":12,"AnnuityRate":-2,"TransactionAmount":100,"TransactionPercentage":12,"Frequency":26,"WithdrawalPreference":1,"GuaranteePeriod":12,"SpousePension":1.1,"MaturityAmount":100,"AnnuityEscalationBasis":3,"AnnuityEscalationPercentage":1.1,"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","Term":12,"BackOfficeID":13573,"BackOfficeSync":1}'
Request examples 
{
  "TransactionType": 5,
  "WithdrawalStyle": 2,
  "TFCBasis": 2,
  "FundBasis": 1,
  "FundAmount": 100,
  "FundPercentage": 12,
  "IncomeRate": 12,
  "IncomePreference": 1,
  "TFCAmount": 100,
  "TFCPercentage": 12,
  "AnnuityRate": -2,
  "TransactionAmount": 100,
  "TransactionPercentage": 12,
  "Frequency": 26,
  "WithdrawalPreference": 1,
  "GuaranteePeriod": 12,
  "SpousePension": 1.1,
  "MaturityAmount": 100,
  "AnnuityEscalationBasis": 3,
  "AnnuityEscalationPercentage": 1.1,
  "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",
  "Term": 12,
  "BackOfficeID": 13573,
  "BackOfficeSync": 1
}
Response examples (201) 
{
  "success": true,
  "data": {
    "TransactionGUID": "61895427-011A-9214-B13E-FCE305CB4112",
    "TransactionType": 5,
    "PensionGUID": "76895427-011A-9214-B13E-FCE305CB4467",
    "WithdrawalStyle": 2,
    "TFCBasis": 2,
    "FundBasis": 1,
    "FundAmount": 100,
    "FundPercentage": 12,
    "IncomeRate": 12,
    "IncomePreference": 1,
    "TFCAmount": 100,
    "TFCPercentage": 12,
    "AnnuityRate": -2,
    "TransactionAmount": 100,
    "TransactionPercentage": 12,
    "Frequency": 26,
    "WithdrawalPreference": 1,
    "GuaranteePeriod": 12,
    "SpousePension": 1.1,
    "MaturityAmount": 1000,
    "AnnuityEscalationBasis": 3,
    "AnnuityEscalationPercentage": 1.1,
    "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",
    "Term": 10,
    "BackOfficeID": "F7FBB6B1-2D90-485C-AE89-9F9FA0426F1E",
    "BackOfficeSync": 1,
    "FormattedValues": {
      "TFCBasis": "Max",
      "Frequency": "Paid Fortnightly",
      "FundBasis": "Total Fund",
      "StartDate": "01/01/2024",
      "TFCAmount": "£100",
      "FundAmount": "£100",
      "IncomeRate": "12%",
      "StartBasis": "Specific Date",
      "AnnuityRate": "-2%",
      "PensionGUID": "My Pension",
      "SpousePension": "1%",
      "TFCPercentage": "12%",
      "FundPercentage": "12%",
      "MaturityAmount": "£1000",
      "TransactionType": "Pension Income",
      "WithdrawalStyle": "Lifetime Annuity",
      "TransactionAmount": "£100",
      "WithdrawalPreference": "Tax free",
      "AnnuityEscalationBasis": "Fixed",
      "AnnuityEscalationPercentage": "1%"
    }
  }
}
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 pension withdrawal in household"
}