# 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 Info This API is only available for Premium accounts. :::

# On this page

# 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:

# Listing details

# Development details

# Property details

# Available sources

New sources might be added in the future.

Some housing providers will also have custom sources set up for importing leads via their own portals.

# Schemes list

# Filtering

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

• createdAt: the timestamp when the lead was created.
• isArchived: true if the lead has been archived, otherwise it is false.
• externalRef: the external reference.
• 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.
• listing.id: the ID of this listing linked to the lead.
• listing.name: the name of this listing linked to the lead.
• listing.development.id: the id of the development for the listing that the lead is linked.
• development.id: id of the development linked to the lead.
• property.id: id of the property linked to the lead.
• property.propertyNumber: number/name of the property linked to the lead.
• housingProvider.id: id of the housing provider linked to the lead.
• housingProvider.name: name of the housing provided linked to the lead.
• customer.id: the lead's customer id.
• customer.firstName: the lead's first name.
• customer.lastName: the lead's last name.
• customer.fullName: the lead's full name.
• customer.phone: the lead's phone number.
• customer.email: the lead's email address.

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

• eq: equal
• 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
• like: standard like operator, use * for any amount of chars and _ for a single one

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 list 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.

# Assignable Sources

New sources might be added in the future.

Some housing providers will also have custom sources set up for importing leads via their own portals.

If a lead is not assigned to any of the above sources or a custom portal, it will be assigned to the source KPro API (6).

# Living Circumstances

# Working Circumstances

# Home Ownership Statuses

# Example

Only include fields that your system uses. If your 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. While there is no need to use both, they have both been included in the JSON to demonstrate what it may look like.

{
  "data": [
    {
      "externalRef": "A-23445",
      "email" : "m.g.scott@mspc.com",
      "sendEmailConfirmation": false,

      "title": "Mr",
      "firstName": "Michael",
      "lastName": "Scott",
      "phone": "07987654321",
        
      "dateOfBirth": "1975-11-21",
      "annualHouseholdIncome": 40000,
      "deposit": 12000,

      "livingCircumstance": 3, // Home owner
      "homePostcode": "D8M 1KE",
      "homeAddress": "17 Condo Lane",
      "dependants": 0,

      "workingCircumstance": 9, // Self employed
      "workPostcode": "SC4 4RN",
      "workAddress": "1725 Slough Avenue",
      "occupation": "Founder, Owner and CEO",
      "employerName": "Michael Scott Paper Company",

      "armedForcesMember": false,
      "keyworker": false,
      "hasDisability": false,
      "housingWaitingList": false,
      "firstTimeBuyer": false,
      "eligibleCitizen": true,
      "homeOwnershipStatus": 3, // Owns a property but it is currently in a selling process
      "additionalInfo": "...",
      
      "listingId": 1234,
      "listingExternalRef": "L-34523",
      
      "propertyId": 12345,
      "propertyExternalRef": "P-67932",
      
      "bedrooms": [2,3]
    },
    { ... },
    { ... }
  ]
}

# 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. A successful request will respond with HTTP code 200, but no response body.

# Successful response

Once a successful import request has been received by the API, a response including the total leads that were successfully imported and an array of any leads that were not imported and the reason why.

# Example

{
  "imported": 5,
  "notImported": [
    {
      "data": { Data for the lead that was sent in the request },
      "reason": "An enquiry with the external reference 123456 already exists from this source. Please ensure that each enquiry has a unique external reference."
    },
    { ... },
    { ... }
 ]
}