Create contribution

POST /api/v2/household/{HouseholdGUID}/pensions/{PensionGUID}/contributions

Bearer auth

This endpoint allows users to create a new pension contribution.

Path parameters

HouseholdGUID string(uuid) Required

The HouseholdGUID of the client.
PensionGUID string(uuid) Required

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

application/json

Body Required

TransactionType integer Required

TransactionType must be 1.

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
TransactionAmount number(float) | null

This field is required if:

For pension type 2:

If TransactionPercentage, EmployerAmount and EmployerPercentage all = 0 or NULL. Needs to be greater than 0.

For pension type 3:

The pension does not have a linked income. Needs to be greater than 0.

The pension has a linked income but TransactionPercentage, EmployerAmount and EmployerPercentage all = 0 or NULL. Needs to be greater than 0.
TransactionPercentage number(float) | null

This field is required if:

For pension type 2:

If TransactionAmount, EmployerAmount and EmployerPercentage all = 0 or NULL. Needs to be greater than 0.

For pension type 3:

The pension has a linked income but TransactionAmount, EmployerAmount and EmployerPercentage all = 0 or NULL. Needs to be greater than 0.
LinkedIncomeGUID string(uuid) | null

The LinkedIncomeGUID can only be added or updated for pension contributions when the PensionType is equal to 3. Additionally, the LinkedIncomeGUID must reference an income with an IncomeType of 1 and must share the same owner as the associated pension.

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
LinkedSavingsGUID string(uuid) | 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}/pensions/contributions/options
ContributionMethod 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}/pensions/contributions/options
EmployerAmount number(float) | null

This field is required if:

For pension type 2:

If TransactionAmount, TransactionPercentage and EmployerPercentage all = 0 or NULL. Needs to be greater than 0.

For pension type 3:

The pension has a linked income but TransactionAmount, TransactionPercentage and EmployerPercentage all = 0 or NULL. Needs to be greater than 0.
EmployerPercentage number(float) | null

This field is required if:

For pension type 2:

If TransactionAmount, TransactionPercentage and EmployerAmount all = 0 or NULL. Needs to be greater than 0.

For pension type 3:

The pension has a linked income but TransactionAmount, TransactionPercentage and EmployerAmount all = 0 or NULL. Needs to be greater than 0.
Frequency 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
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}/pensions/contributions/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}/pensions/contributions/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.

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
EndEventGUID string(uuid) | null

This field is required if the value of EndBasis = 4 and the value of Frequency is not = 120. 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}/pensions/contributions/options
EndAge integer | null

This field is required if the value of EndBasis = 2 or 7 and the value of Frequency is not = 120. 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. 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

201 application/json

Success
Hide response attributes Show response attributes object
- success boolean
  
  Default value is true.
- data object
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object
  
  TransactionGUID string(uuid)
  
  TransactionType integer
  
  PensionGUID string(uuid)
  
  LinkedIncomeGUID string(uuid)
  
  LinkedSavingsGUID string(uuid)
  
  ContributionMethod integer
  
  TransactionAmount number(float)
  
  TransactionPercentage number(float)
  
  EmployerAmount number(float)
  
  EmployerPercentage number(float)
  
  Frequency integer
  
  StartBasis integer
  
  StartEventGUID string(uuid)
  
  StartAge integer
  
  StartDate string
  
  EndBasis integer
  
  EndEventGUID string(uuid)
  
  EndAge integer
  
  EndDate string
  
  BackOfficeID string
  
  BackOfficeSync integer
  
  FormattedValues object
  
  Additional properties are allowed.
403 application/json

Permission error.
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message string
404 application/json

Household not found
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message string
422 application/json

Validation error.
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message string
- data object
  
  Example validation error message.
  
  Additional properties are allowed.
  
  Hide data attribute Show data attribute object
  
  ClientGUID array[string]
500 application/json

Internal server error.
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message string

POST /api/v2/household/{HouseholdGUID}/pensions/{PensionGUID}/contributions

curl \
 -X POST https://api.fincalc.co.uk/api/v2/household/{HouseholdGUID}/pensions/{PensionGUID}/contributions \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"TransactionType":2,"TransactionAmount":5000.1,"TransactionPercentage":12,"LinkedIncomeGUID":"D5BAED8D-3A5F-44B5-BC6D-9E8C7646C9D3","LinkedSavingsGUID":"D5BAED8D-3A5F-44B5-BC6D-9E8C7646C9D3","ContributionMethod":1,"EmployerAmount":5000.1,"EmployerPercentage":12,"Frequency":26,"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": 2,
  "TransactionAmount": 5000.1,
  "TransactionPercentage": 12,
  "LinkedIncomeGUID": "D5BAED8D-3A5F-44B5-BC6D-9E8C7646C9D3",
  "LinkedSavingsGUID": "D5BAED8D-3A5F-44B5-BC6D-9E8C7646C9D3",
  "ContributionMethod": 1,
  "EmployerAmount": 5000.1,
  "EmployerPercentage": 12,
  "Frequency": 26,
  "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": "055CAE9F-6167-4186-8DE2-EC994D2222A2",
    "TransactionType": 1,
    "PensionGUID": "2A05D34A-7B97-40F6-B7B6-11D77C7A8A8A",
    "LinkedIncomeGUID": "681C02ED-0D67-4392-A1C2-6856C84E4E4E",
    "LinkedSavingsGUID": "6B25H34A-6697-40F6-B7B6-11D77C7A77AA",
    "ContributionMethod": 1,
    "TransactionAmount": 1500,
    "TransactionPercentage": 1,
    "EmployerAmount": 1500,
    "EmployerPercentage": 1,
    "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": "Event",
      "Frequency": "Paid Weekly",
      "StartDate": "01/01/2024",
      "StartBasis": "Specific Age",
      "PensionGUID": "My Big Pension",
      "EndEventGUID": "API Tester",
      "EmployerAmount": "£1,500",
      "TransactionType": "Pension Contribution",
      "LinkedIncomeGUID": "Salary",
      "LinkedSavingsGUID": "Current Account",
      "TransactionAmount": "£1,500",
      "ContributionMethod": "Relief at source",
      "EmployerPercentage": "1%",
      "TransactionPercentage": "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 contribution in household"
}