Create asset

POST /api/v2/household/{HouseholdGUID}/assets

Bearer auth

This endpoint allows users to create a new asset for a household.

Path parameters

HouseholdGUID string(uuid) Required

The HouseholdGUID of the client.

application/json

Body

Owner

Not set directly. Can be set as belonging to: the main client (ClientGUID from Household) ; the related client (RelatedClientGUID from Household); jointly owned by the main client and the related client. To set owned by the main client set ClientGUID as ClientGUID. To set owned by the related client set ClientGUID as RelatedClientGUID. To set as jointly owned set ClientGUID as ClientGUID, set JointOwnerClientGUID as RelatedClientGUID.
ClientGUID string(uuid) Required

ClientGUID must be in the household. See Owner for details on what to set.
AssetDescription string Required

The following characters are not permitted: \:*"<>|'

Maximum length is 50.
AssetType 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}/assets/options
CurrentValue number(float) Required
JointOwnerClientGUID string(uuid) | null

JointOwnerClientGUID must be in the household. See Owner for details on what to set.
AssetPurchased 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}/assets/options
StartBasis integer | null

This field is required if the value of AssetPurchased = 2. Determines the basis of the timing of the Asset Purchase.

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}/assets/options
StartEventGUID string(uuid) | null

This field is required if the value of StartBasis = 4 and the value of AssetPurchased = 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}/assets/options
StartAge integer | null

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

StartAge must be in the future.

Determines the age at which the Asset is to be Purchased.

Minimum value is 0, maximum value is 130.
StartDate string | null

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

StartDate should be in the future.

Determines the Asset Purchase date.

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.
PurchasedValue integer | null
AssetDisposal 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}/assets/options
EndBasis integer | null

This field is required if the value of AssetDisposal = 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}/assets/options
EndEventGUID string(uuid) | null
This field is required if any of the following conditions are met:
- The value of AssetDisposal = 1 and the value of AssetPurchased = 1 and the value of EndBasis = 4 (EndEventGUID must be in the future).
- The value of AssetDisposal = 1 and the value of AssetPurchased = 2 and the value of EndBasis = 4 (EndEventGUID must be after starting).
Determines the date at which the Asset is to be disposed of.

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}/assets/options
EndAge integer | null
This field is required if any of the following conditions are met:
- The value of AssetDisposal = 1 and the value of AssetPurchased = 1 and the value of EndBasis = 2 or 7 (EndAge must be in the future).
- The value of AssetDisposal = 1 and the value of AssetPurchased = 2 and the value of EndBasis = 2 or 7 (EndAge must be after starting).
Determines the age at which the Asset is to be disposed of.
Minimum value is 0, maximum value is 130.
EndDate string | null
This field is required if any of the following conditions are met:
- The value of AssetDisposal = 1 and the value of AssetPurchased = 1 and the value of EndBasis = 3 (EndAge must be in the future).
- The value of AssetDisposal = 1 and the value of AssetPurchased = 2 and the value of EndBasis = 3 (EndAge must be after starting).
Determines the Asset Disposal date.

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.
ClearLiabilities integer | null

This field is required if the value of AssetDisposal = 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}/assets/options
TaxBasis integer | null

This field is required if the value of AssetDisposal = 1 or 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}/assets/options
DisposalCosts number(float)
ValueDate string(date) Required
- The value of AssetPurchased = 1 (ValueDate must be before or equal to now).
- The value of AssetPurchased = 2 (ValueDate must be on or before the asset purchase date).
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
ExcludeFormattedValues string | null

If set to any value, formatted values will be excluded from the response.

Responses

201 application/json

Success
Hide response attributes Show response attributes object
- success boolean
  
  Default value is true.
- data object
  
  Hide data attributes Show data attributes object
  
  AssetGUID string(uuid)
  
  ClientGUID string(uuid)
  
  AssetDescription string
  
  AssetType integer
  
  CurrentValue number(float)
  
  JointOwnerClientGUID string(uuid)
  
  AssetPurchased integer
  
  StartBasis integer
  
  StartEventGUID string(uuid)
  
  StartAge integer
  
  StartDate string
  
  PurchasedValue integer
  
  AssetDisposal integer
  
  EndBasis integer
  
  EndEventGUID string(uuid) | null
  
  EndAge integer
  
  EndDate string
  
  ClearLiabilities integer
  
  TaxBasis integer
  
  DisposalCosts number(float)
  
  ValueDate string(date)
  
  BackOfficeID string
  
  BackOfficeSync integer
  
  FormattedValues object
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.
  
  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}/assets

curl \
 --request POST 'https://api.fincalc.co.uk/api/v2/household/{HouseholdGUID}/assets' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"ClientGUID":"3F0B1C88-6D80-4C17-BB3E-1D68E6D26405","AssetDescription":"Our House","AssetType":1,"CurrentValue":450000.1,"JointOwnerClientGUID":"3F0B1C88-6D80-4C17-BB3E-1D68E6D26405","AssetPurchased":1,"StartBasis":4,"StartEventGUID":"F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7","StartAge":42,"StartDate":"2023-05-04","PurchasedValue":300000.1,"AssetDisposal":1,"EndBasis":3,"EndEventGUID":"1A58F6C8-90BD-4D2D-9B22-3E1F9C8E15E7","EndAge":65,"EndDate":"2069-02-01","ClearLiabilities":1,"TaxBasis":1,"DisposalCosts":5000,"ValueDate":"2023-04-25","BackOfficeID":13573,"BackOfficeSync":1,"ExcludeFormattedValues":1}'

Request examples

{
  "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
  "AssetDescription": "Our House",
  "AssetType": 1,
  "CurrentValue": 450000.1,
  "JointOwnerClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
  "AssetPurchased": 1,
  "StartBasis": 4,
  "StartEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
  "StartAge": 42,
  "StartDate": "2023-05-04",
  "PurchasedValue": 300000.1,
  "AssetDisposal": 1,
  "EndBasis": 3,
  "EndEventGUID": "1A58F6C8-90BD-4D2D-9B22-3E1F9C8E15E7",
  "EndAge": 65,
  "EndDate": "2069-02-01",
  "ClearLiabilities": 1,
  "TaxBasis": 1,
  "DisposalCosts": 5000,
  "ValueDate": "2023-04-25",
  "BackOfficeID": 13573,
  "BackOfficeSync": 1,
  "ExcludeFormattedValues": 1
}

Response examples (201)

{
  "success": true,
  "data": {
    "AssetGUID": "E3AEEF8D-3A6F-44B5-BA6D-8E8C7646C9D6",
    "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
    "AssetDescription": "Our House",
    "AssetType": 1,
    "CurrentValue": 450000.1,
    "JointOwnerClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
    "AssetPurchased": 1,
    "StartBasis": 4,
    "StartEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
    "StartAge": 42,
    "StartDate": "2023-05-04",
    "PurchasedValue": 300000.1,
    "AssetDisposal": 1,
    "EndBasis": 3,
    "EndEventGUID": "1A58F6C8-90BD-4D2D-9B22-3E1F9C8E15E7",
    "EndAge": 65,
    "EndDate": "2069-02-01",
    "ClearLiabilities": 1,
    "TaxBasis": 1,
    "DisposalCosts": 5000,
    "ValueDate": "2023-04-25",
    "BackOfficeID": "F7FBB6B1-2D90-485C-AE89-9F9FA0426F1E",
    "BackOfficeSync": 1,
    "FormattedValues": {
      "EndDate": "01/02/2069",
      "EndBasis": "Specific Date",
      "TaxBasis": "Residential property",
      "AssetType": "Main Residence",
      "ValueDate": "25/04/2023",
      "CurrentValue": "£450,000",
      "AssetDisposal": true,
      "DisposalCosts": "£5000",
      "AssetPurchased": true,
      "PurchasedValue": "£300,000",
      "ClearLiabilities": true
    }
  }
}

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 asset in household"
}