Create household

POST /api/v2/household

Bearer auth

This endpoint allows users to create a new household.

application/json

Body Required

ClientGUID string(uuid) Required
RelatedClientGUID string(uuid) | null

RelatedClientGUID must be different from ClientGUID
HouseholdLabel string | null

Maximum length is 60.
BaselineAssumptionSetGUID string(uuid) | null 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/options

Responses

200 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
  
  HouseholdGUID string(uuid)
  
  ClientGUID string(uuid)
  
  RelatedClientGUID string(uuid)
  
  HouseholdLabel string(uuid)
  
  BaselineAssumptionSetGUID string(uuid)
  
  FormattedValues object
  
  Additional properties are allowed.
- message string
403 application/json

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

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

Unable to edit client due to status of clients.
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]

POST /api/v2/household

curl \
 -X POST https://api.fincalc.co.uk/api/v2/household \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"ClientGUID":"3F0B1C88-6D80-4C17-BB3E-1D68E6D26405","RelatedClientGUID":"8B8AE6E3-2F55-4B3E-88F9-1BC0FAD31C6D","HouseholdLabel":"Mr and Mrs Jackson","BaselineAssumptionSetGUID":"EFCAF6D7-B6F5-4D1C-A1F9-9FA92F024B90"}'

Request examples

{
  "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
  "RelatedClientGUID": "8B8AE6E3-2F55-4B3E-88F9-1BC0FAD31C6D",
  "HouseholdLabel": "Mr and Mrs Jackson",
  "BaselineAssumptionSetGUID": "EFCAF6D7-B6F5-4D1C-A1F9-9FA92F024B90"
}

Response examples (200)

{
  "success": true,
  "data": {
    "HouseholdGUID": "5EF25021-1B07-484E-A730-FBF0FD28BA86",
    "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
    "RelatedClientGUID": "8B8AE6E3-2F55-4B3E-88F9-1BC0FAD31C6D",
    "HouseholdLabel": "Mr and Mrs Jackson",
    "BaselineAssumptionSetGUID": "EFCAF6D7-B6F5-4D1C-A1F9-9FA92F024B90",
    "FormattedValues": {
      "ClientGUID": "Terry Jackson",
      "RelatedClientGUID": "June Jackson",
      "BaselineAssumptionSetGUID": "FinCalc Default Fixed 0%"
    }
  },
  "message": "Household created successfully."
}

Response examples (403)

{
  "success": false,
  "message": "You do not have permission to edit the client."
}

Response examples (404)

{
  "success": false,
  "message": "Client not found."
}

Response examples (409)

{
  "success": false,
  "message": "Clients are not in a relationship with each other."
}

Response examples (422)

{
  "success": false,
  "message": "Validation Error.",
  "data": {
    "ClientGUID": [
      "The client guid field is required."
    ]
  }
}