# Application form

Starting an application form
Editing/saving an application form
Submitting an application form
Request fields
Getting a specific application form
Getting user's all application forms
Getting user's draft application forms
Getting user's submitted application forms

Info

For all the endpoints related to the application form, you need to send the header Authorization with value Bearer {access_token}, otherwise an Unauthorized error message will be received.
The only exception is the /api/rest/portal/assessment (POST) endpoint, when submitting the form for logged out users.

# Starting an application form

There are basic cases when starting an application form:

The customer is already signed up
The customer is not signed up

To start an application form when the User is logged in, issue a PUT request to /api/rest/portal/profile/assessment .

To start an application form when the user is not logged in, issue a POST request to /api/rest/portal/assessment . In this case you have to send all the required fields in a one go. (Saving application form is not allowed for logged out users)

Mandatory fields for starting an application:

Field name	Type	Required	Other validation rules	Description
`listingId`	number	true		Reference Id for the listing
`applicants`	array	true		Collection of Applicants. Please see details below.
`applicants[0].firstName`	string	true	Maximum 255 characters	First name of the applicant
`applicants[0].lastName`	string	true	Maximum 255 characters	Last name of the applicant
`applicants[0].email`	string	true	Must be an email address. Maximum 255 characters	Email address of the applicant
`applicants[0].phone`	string	true	Maximum 20 characters	Main phone number of the applicant

Example response:

{
  "application": "object of the attached lead",
  "createdAt": "creation time",
  "development": "object of the attached development",
  "formFields": "object of the application form's fields",
  "id": "id of the created application form",
  "listing": "object of the attached listing",
  "property": "object of the attached property",
  "status": "status of the application form",
  "updatedAt": "latest update date"
}

Starting an application means, that the user can save it, and can modify it later. Once the user submitted the application, it's not editable anymore.

# Editing/saving an application form

To edit an application form, please issue a PUT request to /api/rest/portal/profile/assessment/{id} where id is the started application form's id.

# Submitting an application form

When the user logged in: Please issue a POST request to /api/rest/portal/profile/assessment. When the user not logged in: Please issue a POST request to /api/rest/portal/assessment.

When submitting the application form, all the required fields must be filled in. Please see table below.

# Request fields

The API accepts the following fields:

Field name	Type	Required	Description
`listingId`	number	true	Reference Id for the listing
`propertyId`	number	false	Reference Id for the property
`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
`trustPilotConsent`	boolean	false		Consent to contact by Trustpilot

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

# Getting a specific application form

Please issue a GET request to /api/rest/portal/profile/assessment/{id}. Where id is the application form's id.

# Getting user's all application forms

For getting the user's all application form, please issue a GET request to /api/rest/portal/profile/assessments. This endpoint will return all the draft/submitted application forms for the user.

Example response:

{
  "data": [
    {
      "application": "object of the attached lead",
      "createdAt": "creation time",
      "development": "object of the attached development",
      "formFields": "object of the application form's fields",
      "id": "id of the created application form",
      "listing": "object of the attached listing",
      "property": "object of the attached property",
      "status": "status of the application form",
      "updatedAt": "latest update date"
    },
    {
      ...
    }
  ]
}

# Getting user's draft application forms

For getting the user's draft application forms, please issue a GET request to /api/rest/portal/profile/assessments/draft. This endpoint will return all the draft application forms for the user.

Example response:

{
  "data": [
    {
      "application": "object of the attached lead",
      "createdAt": "creation time",
      "development": "object of the attached development",
      "formFields": "object of the application form's fields",
      "id": "id of the created application form",
      "listing": "object of the attached listing",
      "property": "object of the attached property",
      "status": "status of the application form",
      "updatedAt": "latest update date"
    },
    {
      ...
    }
  ]
}

# Getting user's submitted application forms

For getting the user's submitted application forms, please issue a GET request to /api/rest/portal/profile/assessments/submitted. This endpoint will return all the draft application forms for the user.

Example response:

{
  "data": [
    {
      "application": "object of the attached lead",
      "createdAt": "creation time",
      "development": "object of the attached development",
      "formFields": "object of the application form's fields",
      "id": "id of the created application form",
      "listing": "object of the attached listing",
      "property": "object of the attached property",
      "status": "status of the application form",
      "updatedAt": "latest update date"
    },
    {
      ...
    }
  ]
}

← Register interest Featured Housing Providers →