# Application Forms API

Info

This API is only available for Premium accounts.

# On this page

Basic information
- Statuses
- Site
Get application forms
Adding application forms
Updating application forms
Submitting application forms
Un-submitting application forms

# Basic information

Application forms are essentially extended versions of leads. Technically, multiple application forms can be associated with each lead.

# Statuses

Application forms can have three statuses:

Draft
Submitted
Un-submitted

Draft state: This is the default state. This means that users have not completed filling out the form yet. Any application form in draft status can be updated at any time using the appropriate API endpoint.

Submitted state: The application form has already been submitted, and its contents cannot be modified. An exception to this is the un-submission of the form, which can be initiated by the Housing Provider (for example, if the client wishes to make changes to a previously submitted application form).

Un-submitted state: This special status occurs when the Housing Provider initiates the un-submission of a previously submitted form. In this case, the system creates a copy of the previously submitted application form, placing it in a draft state, allowing clients to continue editing the previously submitted form.

It's important to note that in this scenario, the application IDs change because the original application form transitions into an unsubmitted state, and the new application form will have a new application form ID.

# Site

We can define a so-called 'site' for application forms, which essentially represents the source. If this is not provided, every created application form, its associated lead, and the customers created by the application form will be created within the scope of the KPRO API site. Depending on the configuration, Housing Providers can have their own siteIds. Please contact us regarding this.

# Get application forms

The endpoint to get application forms is:

GET to /api/rest/open/assessments

Remember you need to pass the QueryString parameter api_key with your API key to get access to the resources.

# Export payload

All responses are JSON encoded, and as they are paginated, the data is contained into an envelope:

{
  "data": [items],
  "pagination": {
    "currentPage": 2, // current page number
    "perPage": 10,    // number of items to be shown per page
    "total": 212,     // total number of items
    "from": 11,       // number of the first item in the result
    "to": 20,         // number of the last item in the result  
    "lastPage": 23,   // last page number
  },
  "links": {
    "first": "url to the first page",
    "prev": "url to the previous page",
    "next": "url to the next page",
    "last": "url to the last page",
  }
}

where items is the collection of application forms. Each application form is an object with the following fields:

Field name	Type	Nullable	Description
`id`	number	false	Application form reference in Keaze
`leadId`	number	false	Application form's Lead reference in Keaze
`site`	object	false	Site details
`status`	string	false	Application form status. (draft, submitted,un-submitted)
`development`	object	true	Development details
`listing`	object	true	Listing details
`property`	object	true	Property details
`applicants`	array	false	Array of the applicants

# Site details

Field name	Type	Nullable	Description
`id`	number	false	Site reference in Keaze
`name`	string	false	Site name

# Listing details

Field name	Type	Nullable	Description
`id`	number	false	Listing reference in Keaze
`name`	string	false	Listing name

# Property details

Field name	Type	Nullable	Description
`id`	number	false	Property reference in Keaze
`name`	string	true	Independent unit name, when it does not belong to a development

# Applicant details

Field name	Type	Description
`email`	string	Email address of the applicant
`title`	string	Title of the applicant.
`firstName`	string	First name of the applicant
`middleNames`	string	Middle names of the applicant
`lastName`	string	Family name of the applicant
`previousSurname`	string	Previous surname of the applicant
`maritalStatus`	number	Marital status id of the applicant. Please see: Marital statuses
`relationshipToPrimary`	number	Relationship id of the joint applicant. Please see: Relationship statuses
`phone`	string	Main phone number of the applicant
`homePhone`	string	Home phone number of the applicant
`workPhone`	string	Work phone number of the applicant
`mobilePhone`	string	Mobile phone of the applicant
`dateOfBirth`	string	Birth date of the applicant
`nationalInsuranceNumber`	string	Applicant's NINO number
`livingCircumstance`	number	Living circumstance id of the applicant. Please see: Living circumstances
`addressSameAsMainApplicant`	boolean	True if the applicant has the same address as the main applicant
`homeAddressLine1`	string	Applicant's home address line 1
`homeAddressLine2`	string	Applicant's home address line 2
`homePostcode`	string	Applicant's home postcode
`homeLocalAuthorityId`	number	Applicant's local authority Id. Please see: Local authorities or Getting local authorities from the postcode
`homeTown`	string	Applicant's home town
`homeCounty`	number	Applicant's home county id. Please see: Counties
`homeMoveInDate`	string	Date the applicant moved into their current home
`previousAddresses`	array	Collection of applicant's previous homes. Please see table below for details.
`workingCircumstance`	number	Working circumstance id of the applicant. Please see: Working circumstances
`occupation`	string	Applicant's occupation
`employerName`	string	Applicant's employer name
`employmentStartDate`	string	Applicant's employment start date.
`workAddressLine1`	string	Applicant's work address line 1
`workAddressLine2`	string	Applicant's work address line 2
`workPostcode`	string	Applicant's work postcode
`workTown`	string	Applicant's work town
`workCounty`	number	Applicant's work county id. Please see: Counties
`workLocalAuthorityId`	number	Applicant's work local authority id. Please see: Local authorities or Getting local authorities from the postcode
`employersContactNumber`	string	Applicant's Employer phone number
`employersContactEmail`	string	Applicant's Employer email address
`annualSalary`	number	Applicant's annual salary
`annualBonuses`	number	Applicant's bonuses/year
`monthlyOtherIncome`	number	Applicant's other income/month
`monthlyTaxCredits`	number	Applicant's monthly tax credits
`monthlyDisabilityAllowance`	number	Applicant's monthly disability allowance
`monthlyMaintenance`	number	Applicant's monthly maintenance costs
`monetaryGift`	number	Applicant's monetary gift
`deposit`	number	Applicant's deposit
`savings`	number	Applicant's savings
`monthlyCreditCardAndLoanPayments`	number	Applicant's monthly credit card and loan payments
`monthlyRent`	number	Applicant's current monthly rent
`creditCardBalance`	number	Applicant's current credit card balance
`hasLoans`	boolean
`loanBalance`	number	Applicant's loan balance
`loanPurpose`	string	Applicant's loan purpose
`loanEndDate`	string	Applicant's loan end date
`failedLoanOrCreditAgreement`	boolean	Applicant's failed to keep up on a loan or any form of credit agreement
`declaredBankrupt`	boolean	Applicant's declared bankrupt or has an unsatisfied CCJ within the last 6 years
`enteredIVA`	boolean	Applicant's entered into an IVA (Individual Voluntary Credit Agreement)
`councilWaitingListReferenceNumber`	string	Applicant's council waiting list reference number
`ownsProperty`	boolean	Applicant owns a property
`homeOwnershipStatus`	number	Applicant home ownership status. Please see: Home Ownership Statuses
`currentHomeBeds`	number	Applicant's current home bedrooms number
`ownPets`	boolean	Applicant has pets
`dependants`	number	Applicant's dependants number
`helpToBuyReference`	string	Applicant's Help to buy reference if applicable
`helpToBuyRegistered`	boolean	Applicant is registered in Help to buy
`homeBuyRegistered`	boolean	Applicant is registered in Home buy
`laRegistered`	boolean	Applicant is registered in London Authority
`nationality`	number	Applicant's nationality
`ethnicity`	number	Applicant's ethnicity
`religion`	number	Applicant's religion
`sexuality`	number	Applicant's sexuality
`gender`	number	Applicant's gender
`relatedToHAWorker`	boolean
`relationshipToHAWorker`	number
`MODWorker`	boolean	True if applicant is a Ministry of defense worker/Surviving Partner
`anyoneInHouseholdDisabled`	boolean	True if the applicant consider anyone in household to be disabled
`registeredDisabled`	boolean	True if the applicant is registered disabled
`wheelchairUser`	boolean	True if the applicant is a wheelchair user
`accessibilityNeeds`	string	Applicant's accessibility needs (if any)
`adultsLiveInHome`	number	Number of adults who will live in the new home
`completedHTB`	boolean	Completed Help to Buy
`HTBApplicationNumber`	string	Help to Buy application number
`immediateFamilyInLocalAuthority`	boolean	Do you have immediate family who live in the local authority in which you are applying for?
`immediateFamilyRelation`	string
`hearAbout`	string	Where did you first see or hear about the development?
`preferredPlots`	array

Previous addresses array:

Field name	Type	Description
`addressLine1`	string	Previous address line 1
`addressLine2`	string	Previous address line 2
`postcode`	string	Previous address postcode
`town`	string	Previous address town
`localAuthorityId`	number	Previous address local authority Id. Please see: Local authorities or Getting local authorities from the postcode
`county`	number	Previous address county id. Please see: Counties
`dateMovedIn`	string	Date when the Applicant moved in to this previous address

# Filtering

The API provides several fields that can be used to filter the results:

createdAt: the timestamp when the application form was inserted into the KPRO database.
status: the status of the application form. Can be: submitted, un-submitted, draft.
listing.id: the ID of this listing linked to the application form.
listing.name: the name of this listing linked to the application form.
listing.development.id: the id of the development for the listing that the application form is linked.
development.id: id of the development linked to the application form.
property.id: id of the property linked to the application form.
property.propertyNumber: number/name of the property linked to the application form.
customer.id: the application form's main applicant's customer id.
customer.firstName: the application form's main applicant's first name.
customer.lastName: the application form's main applicant's last name.
customer.fullName: the application form's main applicant's full name.
customer.phone: the application form's main applicant's phone number.
customer.email: the application form's main applicant's email address.

and several operators to be used in conjunction with the fields:

not: not equal
gt: greater than (for numbers, date and timestamps)
lt: less than (for numbers, date and timestamps)
gte: greater than or equal to (for numbers, date and timestamps)
lte: less than or equal to (for numbers, date and timestamps)
ltt: less than tomorrow's date, useful for datetime or timestamp fields when the filter value is a date without the time component
in: in a list of values separated by commas
notin: not in a list of values separated by commas

Operators should be placed after the fields, separated by a dot (.). When multiple filters are specified, the AND logic operator will be used (except when using square brackets at the end of the parameter name to replace in and notin operators). When no operator is specified for a filter, the usual equal comparison is applied.

In order to filter dates and timestamps, use the ISO date format YYYY-MM-DD for dates, and if you want to include hours and minutes, use YYYY-MM-DD HH:mm. Notice that in all cases, UTC date/time is used.

Examples

To get application forms created between 01-Mar-2021 and 10-Mar-2021, inclusive. Notice as the createdAt field is a timestamp, you should use the operator ltt to include application forms created at any time on 10-Mar-2021.

/api/rest/open/assessments?createdAt.gte=2021-03-01&createdAt.ltt=2021-03-10

To get leads created between 11-Mar-2021 10:00 and 11:00, inclusive.

/api/rest/open/assessments?createdAt.gte=2021-03-11 10:00&createdAt.lte=2021-03-11 11:00

# Bracket option

Brackets can be used instead of values separated by commas to replace the operators in and notin.

Examples

listing.id[]=1&listing.id[]=2 is the same as listing.id.in=1,3
listing.id.not[]=1&listing.id.not[]=2 is the same as listing.id.notin=1,3

# Sorting

By default results are sorting by createdAt descending, but you can change it by using parameter sort and the field of fields you want to sort by, separated by comma, as the value. Fields are sorted ascending, but you use the minus symbol (-) in front of any of fields to change the order to descending.

Example, to sort first by listing.id descending, and then by createdAt also descending, use: sort=-site.id,-createdAt

# Pagination

Results are paginated based on parameters page (page number, optional, default is 1) and size (maximum number of records to return per page, optional, default is 100, maximum possible value is 1000).

# Adding application forms

To start an application form, issue a POST request to /api/rest/open/assessments.

# Minimum Payload

The payload must be JSON encoded.

{
  "listingId": xxx, // Keaze listingId reference
  "applicants": [applicant]
}

When starting an application the following fields are required:

listingId
applicant at least one applicant
applicant[0].email applicant's email address
applicant[0].firstName applicant's first name
applicant[0].lastName applicant's last name
applicant[0].phone applicant's phone

An example payload should look like this:

{
    "listingId": 1444,
    "applicants": [
      {
        "email": "john.smith1990@gmail.com",
        "firstName": "John",
        "lastName": "Smith",
        "phone": "074712345678"
      }
    ]
}

After sending the request above, the system follows the following logic:

If the applicant already has a lead associated with the same listingId, no new lead record is created. However, a new application form record is created for this lead, and it is initially set to the 'draft' status.

If the applicant does not have a lead record for this listing, a new lead record is created, and an application form record (draft state) is immediately attached to it.

Example response after sending the example request above:

{
    "id": 721, // Application form Id in Keaze
    "leadId": 446842, // Lead record Id in Keaze. (You can query this record with the Leads API)
    "listing": {
      "id": 1444, // Listing Id in Keaze
      "name": "Preston Road" // Listing name
    },
    "site": {
      "id": 6, // Site Id in Keaze
      "name": "Kpro API" // Site name
    },  
    "property": null, // Property object (if defined in request)
    "status": "draft", // Status of the Application form
    "applicants": [
    {
        "email": "john.smith1990@gmail.com", // main applicant email
        "phone": "074712345678", // main applicant phone
        "lastName": "Smith", // main applicant last name
        "firstName": "John", // main applicant first name
        "customerId": 344919 // customer record Id created for applicant
    }
    ],
    "updatedAt": "2023-10-17T13:38:50+00:00", 
    "createdAt": "2023-10-17T13:38:50+00:00"
}

Afterward, there is the possibility to update the application form, as described in the 'Updating Application form' section.

As an alternative, there is an option to submit the entire application form. In this case, however, it requires filling in additional fields. For full submission, we continue to use the existing URL and method but define the submit = true parameter in the request.

{
    "listingId": 1444,
    "submit": true,
    "applicants": [
      {
        "email": "john.smith1990@gmail.com",
        "firstName": "John",
        "lastName": "Smith",
        "phone": "074712345678",
        ...
      }
    ]
}

# Full payload

{
  "listingId": 1444,
  "propertyId": 2333,
  "siteId": 1,
  "submit": true,
  "applicants": [
    {
      "email": "john.smith1990@gmail.com",
      "title": "mr",
      "firstName": "John",
      "middleNames": "Edward",
      "lastName": "Smith",
      "previousSurname": "Doe",
      "dateOfBirth": "1990-05-20",
      "maritalStatus": 1,
      "gender": 1,
      "MODWorker": true,
      "phone": "074712345678",
      "homePhone": "074712345677",
      "workPhone": "0207123456",
      "mobilePhone": "0777123456",
      "nationalInsuranceNumber": "AB123456C",
      "livingCircumstance": 1,
      "homeAddressLine1": "123 Main Street",
      "homeAddressLine2": "Apt 4B",
      "homePostcode": "W1W 7RG",
      "homeLocalAuthorityId": 322,
      "homeTown": "London",
      "homeCounty": 27,
      "homeMoveInDate": "2017-06-12",
      "previousAddresses": [
        {
          "addressLine1": "456 Elm Avenue",
          "addressLine2": "Building A",
          "postcode": "M4 6WX",
          "town": "Manchester",
          "localAuthorityId": 173,
          "county": 62,
          "dateMovedIn": "1999-10-31"
        },
        {
          "addressLine1": "789 Oak Street",
          "addressLine2": "Suite 2C",
          "postcode": "L4 6TX",
          "town": "Liverpool",
          "localAuthorityId": 168,
          "county": 65,
          "dateMovedIn": "2005-08-15"
        }
      ],
      "workingCircumstance": 7,
      "occupation": "Software Engineer",
      "employmentStartDate": "2018-10-24",
      "employerName": "Acme Group",
      "workAddressLine1": "555 Tech Road",
      "workAddressLine2": "Floor 6",
      "workPostcode": "L4 6TX",
      "workTown": "Liverpool",
      "workCounty": 65,
      "workLocalAuthorityId": 168,
      "employersContactNumber": "0207123456",
      "employersContactEmail": "hr@acmegroup.com",
      "annualSalary": 55000,
      "annualBonuses": 12000,
      "monthlyOtherIncome": 1300,
      "monthlyTaxCredits": 1900,
      "monthlyDisabilityAllowance": 2500,
      "monthlyMaintenance": 500,
      "monetaryGift": 2000,
      "deposit": 5000,
      "savings": 11000,
      "monthlyCreditCardAndLoanPayments": 1400,
      "monthlyRent": 1250,
      "creditCardBalance": 4800,
      "hasLoans": true,
      "loanBalance": 4200,
      "loanPurpose": "home improvement",
      "loanEndDate": "2029-03-12",
      "failedLoanOrCreditAgreement": false,
      "declaredBankrupt": false,
      "enteredIVA": false,
      "councilWaitingListReferenceNumber": "CW12345",
      "helpToBuyReference": "HTB6789",
      "ownsProperty": false,
      "homeOwnershipStatus": 1,
      "currentHomeBeds": 2,
      "laRegistered": true,
      "homeBuyRegistered": true,
      "helpToBuyRegistered": true,
      "ownPets": true,
      "dependants": 2,
      "nationality": 1,
      "ethnicity": 1,
      "religion": 2,
      "sexuality": 3,
      "relatedToHAWorker": true,
      "relationshipToHAWorker": 3,
      "anyoneInHouseholdDisabled": true,
      "registeredDisabled": true,
      "wheelchairUser": true,
      "accessibilityNeeds": "No specific needs",
      "adultsLiveInHome": 3,
      "completedHTB": true,
      "HTBApplicationNumber": "XXX1212",
      "immediateFamilyInLocalAuthority": true,
      "immediateFamilyRelation": "sibling",
      "hearAbout": "Online advertisement",
      "preferredPlots": [1212, 1234]
    },
    {
      "email": "jane.doe1985@hotmail.com",
      "title": "ms",
      "firstName": "Jane",
      "middleNames": "Marie",
      "lastName": "Doe",
      "previousSurname": "Johnson",
      "dateOfBirth": "1985-08-10",
      "maritalStatus": 1,
      "gender": 2,
      "MODWorker": false,
      "relationshipToPrimary": 1,
      "phone": "07123456789",
      "homePhone": "07123456788",
      "workPhone": "",
      "mobilePhone": "",
      "nationalInsuranceNumber": "CD987654A",
      "addressSameAsMainApplicant": true,
      "livingCircumstance": 1,
      "homeAddressLine1": "567 Park Avenue",
      "homeAddressLine2": "Apt 3D",
      "homePostcode": "L9 1JB",
      "homeLocalAuthorityId": 168,
      "homeTown": "Liverpool",
      "homeCounty": 65,
      "homeMoveInDate": "2015-03-20",
      "previousAddresses": [
        {
          "addressLine1": "123 Elm Street",
          "addressLine2": "Unit 5B",
          "postcode": "L9 1AB",
          "town": "Liverpool",
          "localAuthorityId": 168,
          "county": 65,
          "dateMovedIn": "2007-12-15"
        },
        {
          "addressLine1": "890 Oak Lane",
          "addressLine2": "Unit A",
          "postcode": "W1W 7RG",
          "town": "London",
          "localAuthorityId": 322,
          "county": 27,
          "dateMovedIn": "2010-06-08"
        }
      ],
      "workingCircumstance": 7,
      "occupation": "Teacher",
      "employmentStartDate": "2010-09-15",
      "employerName": "Maplewood High School",
      "workAddressLine1": "789 School Road",
      "workAddressLine2": "Unit 2A",
      "workPostcode": "W1W 7TF",
      "workTown": "London",
      "workCounty": 27,
      "workLocalAuthorityId": 322,
      "employersContactNumber": "0712345678",
      "employersContactEmail": "hr@maplewoodhigh.edu",
      "annualSalary": 45000,
      "annualBonuses": 8000,
      "monthlyOtherIncome": 1100,
      "monthlyTaxCredits": 1700,
      "monthlyDisabilityAllowance": 2000,
      "monthlyMaintenance": 600,
      "monetaryGift": 2500,
      "deposit": 6000,
      "savings": 8000,
      "monthlyCreditCardAndLoanPayments": 1300,
      "monthlyRent": 1100,
      "creditCardBalance": 3800,
      "hasLoans": false,
      "loanBalance": 0,
      "loanPurpose": "",
      "loanEndDate": "",
      "failedLoanOrCreditAgreement": false,
      "declaredBankrupt": false,
      "enteredIVA": false,
      "councilWaitingListReferenceNumber": "",
      "helpToBuyReference": "",
      "ownsProperty": true,
      "homeOwnershipStatus": 4,
      "currentHomeBeds": 3,
      "laRegistered": false,
      "homeBuyRegistered": false,
      "helpToBuyRegistered": false,
      "ownPets": false,
      "dependants": 1,
      "nationality": 2,
      "ethnicity": 2,
      "religion": 8,
      "sexuality": 7,
      "relatedToHAWorker": true,
      "relationshipToHAWorker": 3,
      "anyoneInHouseholdDisabled": false,
      "registeredDisabled": false,
      "wheelchairUser": false,
      "accessibilityNeeds": "",
      "adultsLiveInHome": 2,
      "completedHTB": false,
      "HTBApplicationNumber": "",
      "immediateFamilyInLocalAuthority": false,
      "immediateFamilyRelation": "",
      "hearAbout": "Friend's recommendation",
      "preferredPlots": [2345, 3456]
    }
  ]
}

# Validation rules

Field name	Type	Required	Description
`listingId`	number	true	Reference Id for the listing
`propertyId`	number	false	Reference Id for the property
`siteId`	number	false	Identifier in KPro Marketing of the site used as a source. Please ask us about your siteId. If not specified, both the lead and customer data will default to 'KPRO API' as the source.
`applicants`	array	true	Collection of Applicants. Please see details below.

Applicants array:

Field name	Type	Required	Other validation rules	Description
`email`	string	true	Must be an email address. Maximum 255 characters	Email address of the applicant
`title`	string	true	Maximum 50 characters	Title of the applicant.
`firstName`	string	true	Maximum 255 characters	First name of the applicant
`middleNames`	string	false	Maximum 255 characters	Middle names of the applicant
`lastName`	string	true	Maximum 255 characters	Family name of the applicant
`previousSurname`	string	false	Maximum 255 characters	Previous surname of the applicant
`maritalStatus`	number	true		Marital status id of the applicant. Please see: Marital statuses
`relationshipToPrimary`	number	false		Relationship id of the joint applicant. Please see: Relationship statuses
`phone`	string	true	Maximum 20 characters	Main phone number of the applicant
`homePhone`	string	false	Maximum 20 characters	Home phone number of the applicant
`workPhone`	string	false	Maximum 20 characters	Work phone number of the applicant
`mobilePhone`	string	false	Maximum 20 characters	Mobile phone of the applicant
`dateOfBirth`	string	true	Date format: Y-m-d (e.g: 2022-01-01), Date must be in the past	Birth date of the applicant
`nationalInsuranceNumber`	string	false	Maximum 255 characters	Applicant's NINO number
`livingCircumstance`	number	true		Living circumstance id of the applicant. Please see: Living circumstances
`addressSameAsMainApplicant`	boolean	true	Not required for the main applicant. Required for additional applicants.	True if the applicant has the same address as the main applicant
`homeAddressLine1`	string	true	Required if: addressSameAsMainApplicant is false. Maximum 255 characters	Applicant's home address line 1
`homeAddressLine2`	string	true	Maximum 255 characters	Applicant's home address line 2
`homePostcode`	string	true	Required if: addressSameAsMainApplicant is false. Maximum 255 characters	Applicant's home postcode
`homeLocalAuthorityId`	number	true	Required if: addressSameAsMainApplicant is false .Maximum 255 characters	Applicant's local authority Id. Please see: Local authorities or Getting local authorities from the postcode
`homeTown`	string	false	Maximum 255 characters	Applicant's home town
`homeCounty`	number	false		Applicant's home county id. Please see: Counties
`homeMoveInDate`	string	true	Date format: Y-m-d, Date must be in the past	Date the applicant moved into their current home
`previousAddresses`	array	false		Collection of applicant's previous homes. Please see table below for details.
`workingCircumstance`	number	true		Working circumstance id of the applicant. Please see: Working circumstances
`occupation`	string	false	Maximum 255 characters	Applicant's occupation
`employerName`	string	true*	Required if the applicant is working. Maximum 255 characters	Applicant's employer name
`employmentStartDate`	string	false	Maximum 255 characters	Applicant's employment start date.
`workAddressLine1`	string	true*	Required if the applicant is working. Maximum 255 characters	Applicant's work address line 1
`workAddressLine2`	string	true*	Required if the applicant is working. Maximum 255 characters	Applicant's work address line 2
`workPostcode`	string	true*	Required if the applicant is working. Maximum 255 characters	Applicant's work postcode
`workTown`	string	false	Maximum 255 characters	Applicant's work town
`workCounty`	number	false		Applicant's work county id. Please see: Counties
`workLocalAuthorityId`	number	true	Required if the applicant is working.	Applicant's work local authority id. Please see: Local authorities or Getting local authorities from the postcode
`employersContactNumber`	string	false	Maximum 255 characters	Applicant's Employer phone number
`employersContactEmail`	string	false	Maximum 255 characters. Must be a valid email address.	Applicant's Employer email address
`annualSalary`	number	true	Must be greater than 0	Applicant's annual salary
`annualBonuses`	number	false	Must be greater or equal 0	Applicant's bonuses/year
`monthlyOtherIncome`	number	false	Must be greater or equal 0	Applicant's other income/month
`monthlyTaxCredits`	number	false	Must be greater or equal 0	Applicant's monthly tax credits
`monthlyDisabilityAllowance`	number	false	Must be greater or equal 0	Applicant's monthly disability allowance
`monthlyMaintenance`	number	false	Must be greater or equal 0	Applicant's monthly maintenance costs
`monetaryGift`	number	false	Must be greater or equal 0	Applicant's monetary gift
`deposit`	number	true	Must be greater or equal 0	Applicant's deposit
`savings`	number	true	Must be greater or equal 0	Applicant's savings
`monthlyCreditCardAndLoanPayments`	number	false	Must be greater or equal 0	Applicant's monthly credit card and loan payments
`monthlyRent`	number	false	Must be greater or equal 0	Applicant's current monthly rent
`creditCardBalance`	number	false	Must be greater or equal 0	Applicant's current credit card balance
`hasLoans`	boolean	false
`loanBalance`	number	true*	Required if applicant's hasLoans == true, Must be greater or equal 0	Applicant's loan balance
`loanPurpose`	string	true*	Required if applicants' hasLoans == true, Maximum 255 characters	Applicant's loan purpose
`loanEndDate`	string	true*	Required if applicant's hasLoans == true, date format: Y-m-d. Must be a future date	Applicant's loan end date
`failedLoanOrCreditAgreement`	boolean	true		Applicant's failed to keep up on a loan or any form of credit agreement
`declaredBankrupt`	boolean	true		Applicant's declared bankrupt or has an unsatisfied CCJ within the last 6 years
`enteredIVA`	boolean	true		Applicant's entered into an IVA (Individual Voluntary Credit Agreement)
`councilWaitingListReferenceNumber`	string	false		Applicant's council waiting list reference number
`ownsProperty`	boolean	false		Applicant owns a property
`homeOwnershipStatus`	number	false		Applicant home ownership status. Please see: Home Ownership Statuses
`currentHomeBeds`	number	false	Must be greater or equal 0	Applicant's current home bedrooms number
`ownPets`	boolean	true		Applicant has pets
`dependants`	number	false	Must be greater or equal 0	Applicant's dependants number
`helpToBuyReference`	string	false	Maximum 100 characters	Applicant's Help to buy reference if applicable
`helpToBuyRegistered`	boolean	false		Applicant is registered in Help to buy
`homeBuyRegistered`	boolean	false		Applicant is registered in Home buy
`laRegistered`	boolean	false		Applicant is registered in London Authority
`nationality`	number	false	Nationality id. Please see: Nationalities	Applicant's nationality
`ethnicity`	number	false	Ethnicity id. Please see: Ethnicities	Applicant's ethnicity
`religion`	number	false	Religion id. Please see: Religions	Applicant's religion
`sexuality`	number	false	Sexuality id. Please see: Sexualities	Applicant's sexuality
`gender`	number	true	Gender id. Please see: Genders	Applicant's gender
`relatedToHAWorker`	boolean	false
`relationshipToHAWorker`	number	true	Required if relatedToHAWorker is true, Please see: Relationships
`MODWorker`	boolean	true		True if applicant is a Ministry of defense worker/Surviving Partner
`anyoneInHouseholdDisabled`	boolean	false		True if the applicant consider anyone in household to be disabled
`registeredDisabled`	boolean	false		True if the applicant is registered disabled
`wheelchairUser`	boolean	false		True if the applicant is a wheelchair user
`accessibilityNeeds`	string	false	Maximum 255 characters	Applicant's accessibility needs (if any)
`adultsLiveInHome`	number	false	Must be greater or equal 0	Number of adults who will live in the new home
`completedHTB`	boolean	false		Completed Help to Buy
`HTBApplicationNumber`	string	false	Maximum 255 characters	Help to Buy application number
`immediateFamilyInLocalAuthority`	boolean	false		Do you have immediate family who live in the local authority in which you are applying for?
`immediateFamilyRelation`	string	false	Required if immediateFamilyInLocalAuthority is true. Maximum 255 characters
`hearAbout`	string	false	Maximum 255 characters	Where did you first see or hear about the development?
`preferredPlots`	array	false	Array of plot numbers

Previous addresses array:

Field name	Type	Required	Other restrictions	Description
`addressLine1`	string	true	Maximum 120 characters	Previous address line 1
`addressLine2`	string	true	Maximum 120 characters	Previous address line 2
`postcode`	string	true	Maximum 120 characters	Previous address postcode
`town`	string	false	Maximum 120 characters	Previous address town
`localAuthorityId`	number	true	Maximum 120 characters	Previous address local authority Id. Please see: Local authorities or Getting local authorities from the postcode
`county`	number	false		Previous address county id. Please see: Counties
`dateMovedIn`	string	true	Date format: Y-m-d. Only past dates allowed	Date when the Applicant moved in to this previous address

# Updating application forms

To update an application form, issue a PATCH request to /api/rest/open/assessments/{id} URL where {id} is the Application form's ID.

With each update request, the complete payload can be sent. However, during update requests, we always use only the minimal validation rules. (See section: Minimum payload)

Please note: You cannot update un-submitted, or submitted application forms.

# Submitting application forms

The submission of the application form can be done in two ways:

If the application form has already been started:

issue a PATCH request to /api/rest/open/assessments/{id} URL where {id} is the Application form's ID, and include the submit=true parameter in the request.

If the application form not started yet:

issue a POST request to /api/rest/open/assessments URL, and include the submit=true parameter in the request.

When submitting the application form, the system goes through the entire validation process, so sending the necessary fields is required.
Additional information can be found in section 2.5.

Please note: You cannot submit un-submitted or submitted application forms. You can only submit application forms that have the 'draft' status.

# Un-submitting application forms

To un-submit an application form, issue a PATCH request to /api/rest/open/assessments/{id}/un-submit URL where {id} is the Application form's ID you want to unsubmit.

In this case, we duplicate the data of the application form, and the old application form enters an 'un-submitted' state, with its content being non-editable from that point forward.
We keep the record only for logging purposes.
The response message includes the newly generated application form ID.

Please note: You cannot un-submit application forms which are not submitted before.

← Leads API Inventory API →