# Leads API

The Leads API is a Bulk API that provides only two endpoints, one to get existing leads from Keaze and another to import new leads to Keaze from other sources. As it is a bulk API you can import several leads in a single request.

Info

This API is only available for Premium accounts.

# On this page

Get leads
Importing leads

# Get leads

The endpoint to get leads from Keaze is:

GET to /api/bulk/open/leads

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 leads. Each lead is an object with the following fields:

Field name	Type	Nullable	Description
`id`	number	false	Lead reference in Keaze
`externalRef`	string	true	Lead external reference if added from an external source
`listing`	object	true	Listing details
`property`	object	true	Property details
`site`	object	false	Object with the `id`, `code` and `name` of the source the lead came in from
`eligibilityStatus`	string	false	`passed`, `considered`, `incomplete` or `failed`
`email`	string	false	E-mail address
`title`	string	true	Title
`firstName`	string	true	Given and middle name
`lastName`	string	true	Family name
`fullName`	string	true	Concatenation of given, middle and family name
`phone`	string	true	Phone number
`dateOfBirth`	string	true	Date of birth using the format YYYY-MM-DD
`livingCircumstance`	object	true	Object with the `id` and `name` of the customer living circumstance
`homeAddress`	string	true	Address where the customer lives
`homePostcode`	string	true	Postcode where the customer lives
`workingCircumstance`	object	true	Object with the `id` and `name` of the customer working circumstance
`workAddress`	string	true	Address where the customer works
`workPostcode`	string	true	Postcode where the customer works
`occupation`	string	true	Occupation
`employerName`	string	true	Employer name
`annualHouseholdIncome`	number	true	Annual household income
`deposit`	number	true	Deposit or savings
`dependants`	number	true	Total of dependants
`eligibleCitizen`	boolean	true	The customer has British, EU/EEA citizen or have indefinite leave to remain
`firstTimeBuyer`	boolean	true	The customer is a first time buyer
`armedForcesMember`	boolean	true	The customer is a member of the armed forces
`hasDisability`	boolean	true	The customer has any known disability
`keyworker`	boolean	true	The customer is a key worker
`housingWaitingList`	boolean	true	The customer is in the council waiting list
`buyingInterestPeriod`	object	true	Object with the `id` and `name` of the customer interest period to buy
`additionalInfo`	string	true	Additional information
`enquiryDate`	string	false	ATOM format Date-time when the lead was created
`updatedAt`	string	false	ATOM format Date-time when the lead was updated
`createdAt`	string	false	ATOM format Date-time when the lead was inserted into the KPRO database

# Listing details

Field name	Type	Nullable	Description
`id`	number	false	Listing reference in Keaze
`externalRef`	string	true	Listing external reference, if provided
`name`	string	false	Listing name
`availabilityStatus`	string	false	Coming soon, For Sale, Sale Under Offer, Sold, ...
`schemeGroup`	string	false	Shared ownership, Discounted market sale, ...
`schemes`	array	false	Array with the schemes codes, usually only one, but in some cases it could contain two, help-to-buy and first-dibs
`Development`	object	true	When the listing advertise properties from a development, this object will contain the details of the development

# Development details

Field name	Type	Nullable	Description
`id`	number	false	Development reference in Keaze
`externalRef`	string	true	Development external reference, if provided
`name`	string	false	Development name
`building`	string	true	Building name if applicable
`street`	string	true	Street name
`postcode`	string	false	Postcode
`town`	string	true	Town

# Property details

Field name	Type	Nullable	Description
`id`	number	false	Property reference in Keaze
`externalRef`	string	true	Property external reference, if provided
`propertyNumber`	string	true	Property number when it belongs to a development
`name`	string	true	Independent unit name, when it does not belong to a development
`newBuild`	boolean	false	If it is a new build or not, when it belongs to a development it is always true
`bedrooms`	number	false	Total of bedrooms
`bathrooms`	number	false	Total of bathrooms

# Available sources

New sources might be added in the future.

Id	Code	Name
1	KZ	Keaze
2	HFL	Homes For Londoners
3	API	Keaze API

# Schemes list

Code	Name
shared-ownership	Shared ownership
help-to-buy	Help to Buy
first-dibs	First Dibs
discounted-market-sale	Discounted market sale
private-sale	Private sale
london-living-rent	London living rent
discount-market-rent	Discounted market rent
rent-to-buy	Rent to Buy (Outside London)
private-rent	Private rent

# Filtering

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

enquiryDate: the timestamp when the lead was created.
createdAt: the timestamp when the lead was inserted into the KPRO database.
eligibilityStatus: the eligibility status, one of these possible values: passed, considered, incomplete, failed
site.id: the portal or platform id the lead came in from. See below the list of all possible values.
site.code: the portal or platform code the lead came in from. See below the list of all possible values.
site.name: the portal or platform name the lead came in from. See below the list of all possible values.

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 leads 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 leads created at any time on 10-Mar-2021.

/api/bulk/open/leads?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/bulk/open/leads?createdAt.gte=2021-03-11 10:00&createdAt.lte=2021-03-11 11:00

To get leads created on or after 01-Mar-2021 and coming from site id 1 or 2.

/api/bulk/open/leads?createdAt.gte=2021-03-01&site.id.in=1,2

To get leads created on or after 01-Mar-2021 and where eligibility status is not incomplete or failed.

/api/bulk/open/leads?createdAt.gte=2021-03-01&eligibilityStatus.notin=incomplete,failed

# Bracket option

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

Examples

site.id[]=1&site.id[]=2 is the same as site.id.in=1,3
site.id.not[]=1&site.id.not[]=2 is the same as site.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 site.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).

# Importing leads

To import leads into Keaze, issue a POST to /api/bulk/open/leads.

# Import payload

The payload must be JSON encoded, and as this is a bulk API, it must be an object with the field data, which value must be an array containing all the leads you want to import as json objects, no matter if it is only one lead or several.

{
  "data": [leads to import],
}

For every lead, only the email address is mandatory. You should only include the fields that exist in your system, although null values are permitted for all of the other fields.

Field name	Type	Description
`externalRef`	string \| integer	External reference, useful to check if the lead was already imported. Maximum length must not exceed 255 characters.
`email`	string	Customer e-email address: mandatory
`sendEmailConfirmation`	boolean	Boolean to specify if when the lead has been imported, an email should be sent to the customer on behalf of the Housing Provider. If not present or null it is considered false
`title`	string	Customer title
`firstName`	string	Given names
`lastName`	string	Family name
`phone`	string	Phone number
`dateOfBirth`	string	Date of birth using the format YYYY-MM-DD
`annualHouseholdIncome`	number	Annual household income
`deposit`	number	Deposit or savings
`livingCircumstance`	number	Integer matching one of the id value in the list of Living Circumstances
`homePostcode`	string	Home post code. Valid UK postcode
`homeAddress`	string	Home address
`dependants`	number	Integer indicating the total of dependants, it could be zero
`workingCircumstance`	number	Integer matching one of the id value in the list of Working Circumstances
`workPostcode`	string	Work post code. Valid UK postcode.
`workAddress`	string	Work address
`occupation`	string	Occupation
`employerName`	string	Employer name
`armedForcesMember`	boolean	Boolean to specify if the customer is a member of the armed forces
`keyworker`	boolean	Boolean to specify if the customer is a key worker
`hasDisability`	boolean	Boolean to specify if the customer has any known disability
`housingWaitingList`	boolean	Boolean to specify if the customer is in the council waiting list
`firstTimeBuyer`	boolean	Boolean to specify if the customer is a first time buyer
`eligibleCitizen`	boolean	Boolean to specify if the customer has British, EU/EEA citizen or have indefinite leave to remain
`additionalInfo`	string	Any additional information
`listingId`	number	Reference of the listing in Keaze
`listingExternalRef`	string	Listing reference in your system. For Keaze to be able to identify the listing when you include this value, listings should have been previously updated with your system's references
`propertyId`	number	Reference of the property in Keaze
`propertyExternalRef`	string	Property reference in your system. For Keaze to be able to identify the property when you include this value, properties should have been previously updated with your system's references
`bedrooms`	array	Array containing the amount of bedrooms the customer is interested in, example: [2,3]
`enquiryDate`	array	Date of the enquiry in: Y-m-d H:i:s format (e.g: 2023-01-03 15:34:12). If left empty/null the actual date stored.

Warning

It is important to include the externalRef field to every lead in the the payload, to avoid Keaze adding leads twice in case some of them are included in another request.

# Living Circumstances

Id	Description label
1	Renting privately
2	London living rent
3	Home owner
4	Housing benefits
5	Council tenant
6	Living in armed forces accommodation
7	A housing association tenant
8	Living with friends or family

# Working Circumstances

Id	Description label
1	Not working - disabled
2	Not working - Looking after children
3	Not working - retired
4	Other
5	Student
6	Unemployed
7	Working full time
8	Working part-time
9	Self employed

# Example

Only include fields that your system uses. If you system is able to provide information about the listings and/or the properties, include one or both fields if possible. You can provide Keaze Identifiers or your system references if they have been previously updated in Keaze.

{
  "data": [
    {
      "externalRef": "I65473",
      "email" : "john.smith1990@gmail.com",
      "sendEmailConfirmation": false,

      "title": "Mr",
      "firstName": "John",
      "lastName": "Smith",
      "phone": "07987 654 321",
        
      "dateOfBirth": "1990-11-21",
      "annualHouseholdIncome": 40000,
      "deposit": 12000,

      "livingCircumstance": 1, // Renting privately
      "homePostcode": "NW11 7HB",
      "homeAddress": "17 Brick Lane",
      "dependants": 0,

      "workingCircumstance": 7, // Working full time
      "workPostcode": "W1W 7RG",
      "workAddress": "36-38 Mortimer St",
      "occupation": "Sales Manager",
      "employerName": "Keaze",

      "armedForcesMember": false,
      "keyworker": false,
      "hasDisability": false,
      "housingWaitingList": false,
      "firstTimeBuyer": true,
      "eligibleCitizen": true,

      "additionalInfo": "...",

      "listingExternalRef": "L-34523",
      "propertyExternalRef": "P-67932",
      "bedrooms": [2,3],
      "enquiryDate": "2023-01-03 14:11:09"
    },
    ...
  ]
}

# Errors

If there's any validation error in any of the leads, no record will be added and the API will respond with HTTP code 422, and an object with attributes message and errors. Message will contain a general description of the error, and errors will contain a collection of objects for every lead that failed, with two fields: customerEmail and errors, the first one with the customer email of the lead, and the second one the list of errors related to each parameter that failed the validation.

← Introduction Application Forms API →