Update household

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://apidocs.fincalc.co.uk/mcp

Standard setup for AI tools providing an mcp.json file

{
  "FinCalc API MCP server": {
    "url": "https://apidocs.fincalc.co.uk/mcp"
  }
}

PUT /api/v2/household/{HouseholdGUID}

Bearer auth

This endpoint allows users to update a household.

Relationships: If a RelatedClientGUID is provided, the related client must already have an established relationship with the client before it can be added to or changed within the household. To create or manage relationships, see the Relationship endpoint.

Errors:

404 Not Found – Returned when the HouseholdGUID, ClientGUID, or RelatedClientGUID cannot be found.
409 Conflict – Returned for any issues not related to permissions.

Additional errors may be returned depending on the associated HTTP status code.

Path parameters

HouseholdGUID string(uuid) Required

The HouseholdGUID of the client.

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
ExcludeFormattedValues string | null

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

Responses

200 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
  
  HouseholdGUID string(uuid)
  
  ClientGUID string(uuid)
  
  RelatedClientGUID string(uuid)
  
  HouseholdLabel string(uuid)
  
  BaselineAssumptionSetGUID string(uuid)
  
  FormattedValues object
- 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.
  
  Hide data attribute Show data attribute object
  
  ClientGUID array[string]

PUT /api/v2/household/{HouseholdGUID}

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

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",
  "ExcludeFormattedValues": 1
}

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 updated successfully."
}

Response examples (403)

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

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."
    ]
  }
}