Create a new client

POST /api/v2/clients

Bearer auth

Create a new client record.

application/json

Body

Title string | null

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

Maximum length is 20.
FirstName string Required

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

Minimum length is 2, maximum length is 50.
Surname string Required

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

Maximum length is 50.
KnownAs string | null

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

Maximum length is 50.
Gender integer Required
An integer representing the gender of the client:
- 1: Male
- 2: Female
- 3: Other
EmailAddress string(email) | null

Maximum length is 64.
Mobile string | null

Maximum length is 20.
DateOfBirth string(date) Required

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. The response will contain an object of formatted values where the date will in the format "d/m/Y".
MaritalStatus 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/clients/options
MarriageAllowance integer | null
An integer representing the status of the clients marriage allowance:
- 1: Yes
- 2: No
NINumber string | null
EmploymentStatus 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/clients/options
OccupationCode string | 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/clients/options

Maximum length is 8.
RetirementPlanned 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/clients/options

This field is required if the value of EmploymentStatus = 1, 2, 3, 4 or 6.
RetirementDate string(date) | null

This field is required if the value of EmploymentStatus = 1, 2, 3, 4 or 6 and the value of RetirementPlanned = 2. 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. The response will contain an object of formatted values where the date will in the format "d/m/Y".
RetirementAge integer | null

This field is required if the value of EmploymentStatus = 1, 2, 3, 4 or 6 and the value of RetirementPlanned = 1.

Minimum value is 0, maximum value is 130.
AddressCountryCode 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/clients/options
AddressLine1 string | null

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

Maximum length is 50.
AddressLine2 string | null

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

Maximum length is 50.
AddressLine3 string | null

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

Maximum length is 50.
AddressLine4 string | null

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

Maximum length is 50.
AddressTown string | null

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

Maximum length is 50.
AddressCounty string | null

Maximum length is 50.
AddressPostCode string | null

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

Maximum length is 20.
IncomeTaxArea integer | null
An integer representing the clients income tax area:
- 1: UK excluding Scotland
- 2: Scotland
- 3: Other
- 4: All at 20%
- 5: No Tax Applied
AdviserUserGUID string(uuid) | null

This field is required if the user company is different to primary company (user is logged into a network company) or if the company has had the adviser field enforced.

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/clients/options
Reference string | null

Maximum length is 50.
ATRGUID 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/clients/options
ClientTierGUID 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/clients/options
FinancialDependenceAge 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/clients/options
AddressFrom string(date) | null

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. The response will contain an object of formatted values where the date will in the format "d/m/Y".
NextReviewDate string(date) | null

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. The response will contain an object of formatted values where the date will in the format "d/m/Y".
LTA object
Hide LTA attributes Show LTA attributes object
- MPAATriggered integer | null
  An integer representing the status of the clients MPAA:
  
  1: Yes
  
  2: No
- MpaTriggerDate string(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. The response will contain an object of formatted values where the date will in the format "d/m/Y". Date should be before or equal to today.
- LTARemainingLumpSum number(float) | null
- LTARemainingLumpSumDeath number(float) | null
- LTAHMRCertificateValue number(float) | null
  This field is required if any of the following conditions are met:
  
  The value of LTAProtectionType = 4 and the value of LTAAppliedFor = 1.
  
  The value of LTAProtectionType = 6 and the value of LTAAppliedFor = 1.
  
  If the value of LTAProtectionType is 4: - LTAHMRCertificateValue must be greater than £1,250,000. - LTAHMRCertificateValue must be less than or equal to £1,500,000.
  
  If the value of LTAProtectionType is 6: - LTAHMRCertificateValue must be greater than £1,000,000. - LTAHMRCertificateValue must be less than or equal to £1,250,000.
- LTAProtectedCashAmount number(float) | null
  
  This field is required if the value of LTAProtectionType = 2 and the value of LTAProtectedLumpSum = 1 LTAProtectedCashAmount must be greater than 0.
  
  Minimum value is 1.
- LTAProtectedCashPercentage number(float) | null
  
  This field is required if the value of LTAProtectionType = 1 and the value of LTAProtectedLumpSum = 1 LTAProtectedCashPercentage must be greater than 0.
  
  Minimum value is 1.
- LTAPrevBCEs integer | null
  This field is required if any of the following conditions are met:
  
  The value of LTAProtectionType = 2
  
  The value of LTAProtectionType = 1 and the value of LTAProtectedLumpSum = 2.
- LTAPercentageLeft number(float) | null
  
  Minimum value is 0, maximum value is 100.
- LTAAppliedFor integer | null
  An integer representing weather or not the client has HMRC protection:
  
  1: Yes
  
  2: No
- LTAProtectionType 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/clients/options This field is required if the value of LTAAppliedFor = 1.
- LTAEnhancementFactor number(float) | null
  
  This field is required if the value of LTAProtectionType = 2.
- LTAProtectedLumpSum integer | null
  An integer representing the clients protected lump sum rights:
  
  1: Yes
  
  2: No
  
  This field is required if any of the following conditions are met:
  
  The value of LTAProtectionType = 1
  
  The value of LTAProtectionType = 2
- InheritedNilRateBand number(float) | null
- InheritedResidenceNilRateBand number(float) | null
- CGTLossesAvailable number(float) | null
- BADRLossesAvailable number(float) | null
- BADRReliefAvailable number(float) | null
- InvestorsReliefAvailable number(float) | null
- TaxFreeCash array[object]
  This field is required if any of the following conditions are met:
  
  The value of LTAProtectionType = 2 and the value of LTAProtectedLumpSum = 1 and the value of LTAPrevBCEs = 1.
  
  The value of LTAProtectionType = 1 and the value of LTAProtectedLumpSum = 2 and the value of LTAPrevBCEs = 1.
  
  The value of LTAProtectionType = 2 and the value of LTAProtectedLumpSum = 2 and the value of LTAPrevBCEs = 1.
  
  An array of objects representing multiple rows of tax-free cash data. Each object should have the following properties: - BCEDate: a date string in the format yyyy-mm-dd. Duplication of BCEDate is not permitted. - BCEAmount: an integer representing the BCE amount. - BCETFC: an integer representing the BCE tax-free cash amount. (Not required if LTAProtectionType = 1 or 2 and LTAProtectedLumpSum = 2)
  
  Updating the array will overwrite any existing data for that client, therefore if adding new rows to the array, data for existing rows should be included in the request.
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
  
  ClientGUID string(uuid)
  
  Title string
  
  FirstName string
  
  Surname string
  
  KnownAs string
  
  Gender integer
  
  EmailAddress string(email)
  
  Mobile string
  
  DateOfBirth string(date)
  
  MaritalStatus integer
  
  MarriageAllowance integer
  
  NINumber string
  
  EmploymentStatus integer
  
  OccupationCode string
  
  RetirementPlanned integer
  
  RetirementDate string(date)
  
  RetirementAge integer
  
  AddressCountryCode integer
  
  AddressLine1 string
  
  AddressLine2 string
  
  AddressLine3 string
  
  AddressLine4 string
  
  AddressTown string
  
  AddressCounty string
  
  AddressPostCode string
  
  IncomeTaxArea integer
  
  AdviserUserGUID string(uuid)
  
  Reference string
  
  ATRGUID string(uuid)
  
  ClientTierGUID string(uuid)
  
  FinancialDependenceAge integer
  
  AddressFrom string(date)
  
  NextReviewDate string(date)
  
  LTA object
  
  Hide LTA attributes Show LTA attributes object
  
  MPAATriggered integer
  
  MpaTriggerDate string(date)
  
  LTARemainingLumpSum number(float) | null
  
  LTARemainingLumpSumDeath number(float) | null
  
  LTAHMRCertificateValue number(float)
  
  LTAProtectedCashAmount number(float)
  
  LTAProtectedCashPercentage number(float)
  
  LTAPrevBCEs integer
  
  LTAPercentageLeft number(float)
  
  LTAAppliedFor integer
  
  LTAProtectionType integer
  
  LTAEnhancementFactor number(float)
  
  LTAProtectedLumpSum integer
  
  InheritedNilRateBand integer
  
  InheritedResidenceNilRateBand integer
  
  CGTLossesAvailable number(float)
  
  BADRLossesAvailable number(float)
  
  BADRReliefAvailable number(float)
  
  InvestorsReliefAvailable number(float)
  
  FormattedValues object
  
  TaxFreeCash array[object]
  
  Hide TaxFreeCash attributes Show TaxFreeCash attributes object
  
  BCEDate string(date)
  
  BCETFC integer
  
  BCEAmount integer
  
  FormattedValues object
  
  Hide FormattedValues attributes Show FormattedValues attributes object
  
  BCEDate string(date)
  
  BCETFC string
  
  BCEAmount string
  
  FormattedValues object
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 attributes Show data attributes object
  
  FirstName array[string]
  
  Surname array[string]
  
  Gender array[string]
  
  DateOfBirth array[string]
403 application/json

Permission error.
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message 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/clients

curl \
 --request POST 'https://api.fincalc.co.uk/api/v2/clients' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"Title":"Mr","FirstName":"John","Surname":"Smith","KnownAs":"Big John","Gender":1,"EmailAddress":"hello@example.com","Mobile":"07777000858","DateOfBirth":"2025-05-04","MaritalStatus":1,"MarriageAllowance":1,"NINumber":"JW001100A","EmploymentStatus":1,"OccupationCode":"AAB00001","RetirementPlanned":1,"RetirementDate":"1990-05-04","RetirementAge":68,"AddressCountryCode":826,"AddressLine1":"216 Newgate Street","AddressLine2":"Address Line 2","AddressLine3":"Address Line 3","AddressLine4":"Address Line 4","AddressTown":"Westminister","AddressCounty":"London","AddressPostCode":"SW1A 1AA","IncomeTaxArea":1,"AdviserUserGUID":"string","Reference":"API Client","ATRGUID":"1205C07E-2697-472A-8A35-73CF78B2A7B6","ClientTierGUID":"0611EC15-173B-4EF0-9FA5-1CFA45D3F51C","FinancialDependenceAge":1,"AddressFrom":"1990-05-04","NextReviewDate":"1990-05-04","LTA":{"MPAATriggered":1,"MpaTriggerDate":"1990-05-04","LTARemainingLumpSum":1500.0,"LTARemainingLumpSumDeath":3000.0,"LTAHMRCertificateValue":42.0,"LTAProtectedCashAmount":42.0,"LTAProtectedCashPercentage":42.0,"LTAPrevBCEs":1,"LTAPercentageLeft":42.0,"LTAAppliedFor":1,"LTAProtectionType":1,"LTAEnhancementFactor":42.0,"LTAProtectedLumpSum":42,"InheritedNilRateBand":42.0,"InheritedResidenceNilRateBand":42.0,"CGTLossesAvailable":42.0,"BADRLossesAvailable":42.0,"BADRReliefAvailable":42.0,"InvestorsReliefAvailable":42.0,"TaxFreeCash":[{"BCETFC":1000000,"BCEDate":"2006-04-07","BCEAmount":1000000},{"BCETFC":2000000,"BCEDate":"2006-04-05","BCEAmount":2000000}]},"ExcludeFormattedValues":1}'

Request examples

{
  "Title": "Mr",
  "FirstName": "John",
  "Surname": "Smith",
  "KnownAs": "Big John",
  "Gender": 1,
  "EmailAddress": "hello@example.com",
  "Mobile": "07777000858",
  "DateOfBirth": "2025-05-04",
  "MaritalStatus": 1,
  "MarriageAllowance": 1,
  "NINumber": "JW001100A",
  "EmploymentStatus": 1,
  "OccupationCode": "AAB00001",
  "RetirementPlanned": 1,
  "RetirementDate": "1990-05-04",
  "RetirementAge": 68,
  "AddressCountryCode": 826,
  "AddressLine1": "216 Newgate Street",
  "AddressLine2": "Address Line 2",
  "AddressLine3": "Address Line 3",
  "AddressLine4": "Address Line 4",
  "AddressTown": "Westminister",
  "AddressCounty": "London",
  "AddressPostCode": "SW1A 1AA",
  "IncomeTaxArea": 1,
  "AdviserUserGUID": "string",
  "Reference": "API Client",
  "ATRGUID": "1205C07E-2697-472A-8A35-73CF78B2A7B6",
  "ClientTierGUID": "0611EC15-173B-4EF0-9FA5-1CFA45D3F51C",
  "FinancialDependenceAge": 1,
  "AddressFrom": "1990-05-04",
  "NextReviewDate": "1990-05-04",
  "LTA": {
    "MPAATriggered": 1,
    "MpaTriggerDate": "1990-05-04",
    "LTARemainingLumpSum": 1500.0,
    "LTARemainingLumpSumDeath": 3000.0,
    "LTAHMRCertificateValue": 42.0,
    "LTAProtectedCashAmount": 42.0,
    "LTAProtectedCashPercentage": 42.0,
    "LTAPrevBCEs": 1,
    "LTAPercentageLeft": 42.0,
    "LTAAppliedFor": 1,
    "LTAProtectionType": 1,
    "LTAEnhancementFactor": 42.0,
    "LTAProtectedLumpSum": 42,
    "InheritedNilRateBand": 42.0,
    "InheritedResidenceNilRateBand": 42.0,
    "CGTLossesAvailable": 42.0,
    "BADRLossesAvailable": 42.0,
    "BADRReliefAvailable": 42.0,
    "InvestorsReliefAvailable": 42.0,
    "TaxFreeCash": [
      {
        "BCETFC": 1000000,
        "BCEDate": "2006-04-07",
        "BCEAmount": 1000000
      },
      {
        "BCETFC": 2000000,
        "BCEDate": "2006-04-05",
        "BCEAmount": 2000000
      }
    ]
  },
  "ExcludeFormattedValues": 1
}

Response examples (201)

{
  "success": true,
  "data": {
    "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
    "Title": "Mr",
    "FirstName": "John",
    "Surname": "Smith",
    "KnownAs": "Big John",
    "Gender": 1,
    "EmailAddress": "hello@example.com",
    "Mobile": "07777000858",
    "DateOfBirth": "1990-05-04",
    "MaritalStatus": 1,
    "MarriageAllowance": 1,
    "NINumber": "JW001100A",
    "EmploymentStatus": 1,
    "OccupationCode": "AAB00001",
    "RetirementPlanned": 1,
    "RetirementDate": "1990-05-04",
    "RetirementAge": 69,
    "AddressCountryCode": 826,
    "AddressLine1": "216 Newgate Street",
    "AddressLine2": "Address Line 2",
    "AddressLine3": "Address Line 3",
    "AddressLine4": "Address Line 4",
    "AddressTown": "Westminister",
    "AddressCounty": "London",
    "AddressPostCode": "SW1A 1AA",
    "IncomeTaxArea": 1,
    "AdviserUserGUID": "D70E4745-6A3E-4706-A3C3-00ED8F547125",
    "Reference": "API Client",
    "ATRGUID": "02B9D638-8292-4823-B809-52DC9E3FB6D4",
    "ClientTierGUID": "594C0C21-D896-4344-93E8-3324D6EE97BD",
    "FinancialDependenceAge": 1,
    "AddressFrom": "1990-05-04",
    "NextReviewDate": "1990-05-04",
    "LTA": {
      "MPAATriggered": 1,
      "MpaTriggerDate": "1990-05-04",
      "LTARemainingLumpSum": 1500.0,
      "LTARemainingLumpSumDeath": 3000.0,
      "LTAHMRCertificateValue": 42.0,
      "LTAProtectedCashAmount": 42.0,
      "LTAProtectedCashPercentage": 42.0,
      "LTAPrevBCEs": 1,
      "LTAPercentageLeft": 42.0,
      "LTAAppliedFor": 1,
      "LTAProtectionType": 1,
      "LTAEnhancementFactor": 42.0,
      "LTAProtectedLumpSum": 42,
      "InheritedNilRateBand": 42,
      "InheritedResidenceNilRateBand": 42,
      "CGTLossesAvailable": 42.0,
      "BADRLossesAvailable": 42.0,
      "BADRReliefAvailable": 42.0,
      "InvestorsReliefAvailable": 42.0,
      "FormattedValues": {
        "LTAPrevBCEs": "Yes",
        "LTAAppliedFor": "Yes",
        "MPAATriggered": "Yes",
        "MpaTriggerDate": "04/05/1990",
        "LTAProtectionType": "Primary Protection",
        "CGTLossesAvailable": "£42",
        "BADRLossesAvailable": "£42",
        "BADRReliefAvailable": "£42",
        "LTAProtectedLumpSum": "Yes",
        "LTARemainingLumpSum": "£1500.00",
        "LTAProtectedCashAmount": "£42",
        "InvestorsReliefAvailable": "£42",
        "LTARemainingLumpSumDeath": "£3000.00",
        "LTAProtectedCashPercentage": "42%"
      },
      "TaxFreeCash": [
        {
          "BCETFC": 1000000,
          "BCEDate": "2006-04-07",
          "BCEAmount": 1000000,
          "FormattedValues": {
            "BCETFC": "£1,000,000",
            "BCEDate": "07/04/2006",
            "BCEAmount": "£1,000,000"
          }
        },
        {
          "BCETFC": 2000000,
          "BCEDate": "2006-04-05",
          "BCEAmount": 2000000,
          "FormattedValues": {
            "BCETFC": "£2,000,000",
            "BCEDate": "05/04/2006",
            "BCEAmount": "£2,000,000"
          }
        }
      ]
    },
    "FormattedValues": {
      "Gender": "Male",
      "ATRGUID": "High",
      "AddressFrom": "04/05/1990",
      "DateOfBirth": "04/05/1990",
      "IncomeTaxArea": "UK excluding Scotland",
      "MaritalStatus": true,
      "ClientTierGUID": "London Branch",
      "NextReviewDate": "04/05/1990",
      "OccupationCode": "Abattoir Inspector",
      "RetirementDate": "04/05/1990",
      "AdviserUserGUID": "Jonathan Thomas",
      "EmploymentStatus": "Employed",
      "MarriageAllowance": true,
      "RetirementPlanned": "Age",
      "AddressCountryCode": "United Kingdom",
      "FinancialDependenceAge": "Not Applicable"
    }
  }
}

Response examples (422)

{
  "success": false,
  "message": "Validation Error",
  "data": {
    "FirstName": [
      "The first name field is required."
    ],
    "Surname": [
      "The surname field is required."
    ],
    "Gender": [
      "The gender field is required."
    ],
    "DateOfBirth": [
      "The date of birth field is required."
    ]
  }
}

Response examples (403)

{
  "success": false,
  "message": "You do not have permission to create clients."
}

Response examples (500)

{
  "success": false,
  "message": "Failed to create client in FinCalc"
}