Create event

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

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

Path parameters

application/json

Body

  • ClientGUID string(uuid) | null

    This field is required if the value of EventBasis = 2: ClientGUID must be in the household.

  • EventLabel string Required

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

    Maximum length is 50.

  • EventBasis integer Required

    An integer representing the status of the type of event:

    • 1: Date
    • 2: Age
    • 3: Linked to another event
  • LinkedEventGUID string(uuid) | null

    This field is required if the value of EventBasis = 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}/events/options

  • OffsetBasis integer | null

    An integer representing before or after:

    • 1: Before
    • 2: After

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

  • OffsetYears integer | null

    This field is required if the value of EventBasis = 3. OffsetYears and OffsetMonths must resolve to a date in the future.

    Minimum value is 0.

  • OffsetMonths integer | null

    OffsetYears and OffsetMonths must resolve to a date in the future.

    Minimum value is 0, maximum value is 11.

  • AgeYears integer | null

    This field is required if the value of EventBasis = 2. Age Years + Age Months should be in the future

    Maximum value is 130.

  • AgeMonths integer | null

    This field is required if the value of EventBasis = 2. Age Years + Age Months should be in the future

    Minimum value is 0, maximum value is 11.

  • EventDate string(date) | null

    This field is required if the value of EventBasis = 1. Date must be after today.

    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.

  • GoalSet integer | null

    Minimum value is 1, maximum value is 2.

  • GoalPriority integer | null

    Minimum value is 1, maximum value is 5.

  • GoalYears1 integer | null

    This field is required if the value of GoalSet = 1. Should be set to an integer from 1 to 50 (inclusive) for the number of years, or set to 99 for Lifetime.

    Minimum value is 1, maximum value is 99.

  • GoalAmount1 integer | null

    This field is required if the value of GoalSet = 1.

    Minimum value is 0.

  • GoalYears2 integer | null

    This field is required if the value of GoalSet = 1 AND the value of GoalAmount2 is set. Should be set to an integer from 1 to 50 (inclusive) for the number of years, or set to 99 for Lifetime.

    Minimum value is 1, maximum value is 99.

  • GoalAmount2 integer | null

    This field is required if the value of GoalSet = 1 AND the value of GoalYears2 is set.

    Minimum value is 0.

  • GoalYears3 integer | null

    This field is required if the value of GoalSet = 1 AND the value of GoalAmount3 is set. Should be set to an integer from 1 to 50 (inclusive) for the number of years, or set to 99 for Lifetime.

    Minimum value is 1, maximum value is 99.

  • GoalAmount3 integer | null

    This field is required if the value of GoalSet = 1 AND the value of GoalYears3 is set.

    Minimum value is 0.

  • GoalYears4 integer | null

    This field is required if the value of GoalSet = 1 AND the value of GoalAmount4 is set. Should be set to an integer from 1 to 50 (inclusive) for the number of years, or set to 99 for Lifetime.

    Minimum value is 1, maximum value is 99.

  • GoalAmount4 integer | null

    This field is required if the value of GoalSet = 1 AND the value of GoalYears4 is set.

    Minimum value is 0.

  • GoalYears5 integer | null

    This field is required if the value of GoalSet = 1 AND the value of GoalAmount5 is set. Should be set to an integer from 1 to 50 (inclusive) for the number of years, or set to 99 for Lifetime.

    Minimum value is 1, maximum value is 99.

  • GoalAmount5 integer | null

    This field is required if the value of GoalSet = 1 AND the value of GoalYears5 is set.

    Minimum value is 0.

  • EventIcon string | null

    Chose one of the preselected font awesome icons. If you do not enter an icon then a default icon will be applied.

    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}/events/options

  • EventColour string | null

    Enter a 6 character hex value without the '#'. If you do not enter a value then a default value will be applied.

Responses

POST /api/v2/household/{HouseholdGUID}/events
curl \
 -X POST https://api.fincalc.co.uk/api/v2/household/{HouseholdGUID}/events \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"ClientGUID":"3F0B1C88-6D80-4C17-BB3E-1D68E6D26405","EventLabel":"Tony's State Pension Age","EventBasis":1,"LinkedEventGUID":"3F0B1C88-6D80-4C17-BB3E-1D68E6D26405","OffsetBasis":1,"OffsetYears":20,"OffsetMonths":5,"AgeYears":55,"AgeMonths":3,"EventDate":"2065-05-04","GoalSet":1,"GoalPriority":3,"GoalYears1":20,"GoalAmount1":15000,"GoalYears2":5,"GoalAmount2":10000,"GoalYears3":4,"GoalAmount3":8000,"GoalYears4":3,"GoalAmount4":4000,"GoalYears5":5,"GoalAmount5":2500,"EventIcon":"fa-solid fa-rings-wedding","EventColour":"C3A1F6"}'
Request examples
{
  "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
  "EventLabel": "Tony's State Pension Age",
  "EventBasis": 1,
  "LinkedEventGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
  "OffsetBasis": 1,
  "OffsetYears": 20,
  "OffsetMonths": 5,
  "AgeYears": 55,
  "AgeMonths": 3,
  "EventDate": "2065-05-04",
  "GoalSet": 1,
  "GoalPriority": 3,
  "GoalYears1": 20,
  "GoalAmount1": 15000,
  "GoalYears2": 5,
  "GoalAmount2": 10000,
  "GoalYears3": 4,
  "GoalAmount3": 8000,
  "GoalYears4": 3,
  "GoalAmount4": 4000,
  "GoalYears5": 5,
  "GoalAmount5": 2500,
  "EventIcon": "fa-solid fa-rings-wedding",
  "EventColour": "C3A1F6"
}
Response examples (201)
{
  "success": true,
  "data": {
    "EventGUID": "E3AEEF8D-3A6F-44B5-BA6D-8E8C7646C9D6",
    "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
    "EventLabel": "Tony's State Pension Age",
    "EventType": 3,
    "EventBasis": 1,
    "LinkedEventGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
    "OffsetBasis": 1,
    "OffsetYears": 20,
    "OffsetMonths": 5,
    "AgeYears": 55,
    "AgeMonths": 3,
    "EventDate": "2065-05-04",
    "GoalSet": 1,
    "GoalPriority": 3,
    "GoalYears1": 20,
    "GoalAmount1": 15000,
    "GoalYears2": 5,
    "GoalAmount2": 10000,
    "GoalYears3": 4,
    "GoalAmount3": 8000,
    "GoalYears4": 3,
    "GoalAmount4": 4000,
    "GoalYears5": 5,
    "GoalAmount5": 2500,
    "EventIcon": "fa-solid fa-rings-wedding",
    "EventColour": "#C3A1F6",
    "FormattedValues": {
      "GoalSet": "Yes",
      "EventDate": "04/05/2065",
      "EventIcon": "rings-wedding",
      "ClientGUID": "Mark Phillips",
      "EventBasis": "Date",
      "GoalAmount1": "£15,000",
      "GoalAmount2": "£10,000",
      "GoalAmount3": "£8,000",
      "GoalAmount4": "£4,000",
      "GoalAmount5": "£2,500",
      "OffsetBasis": "After",
      "GoalPriority": "Medium",
      "LinkedEventGUID": "Tina's State Pension Age"
    }
  }
}
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 event in household"
}