NAV Navbar
CURL

Introduction

Welcome to the Yorlet API Reference. The API is designed to use standard HTTP protocols and return JSON payloads in response to HTTP requests, and are internally implemented based on the RESTful principles.

Authentication

Example Request

curl https://api.yorlet.com/v1/enquiries
  -H "Authorization: Bearer {API_KEY}"

Make sure to replace {API_KEY} with your API key.

To use the API you must authenticate a request using your API key. You can find the key in the Dashboard. There are two API keys in the dashboard: Publishable and Secret. You can find out more about the differences here.

The access token should be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer {API_KEY}

Expanding Objects

Example Request

curl https://api.yorlet.com/v1/applications/8jfkFPL90d
  -H "Authorization: Bearer {access_token}"
  -d expand[]=unit

Many objects contain the ID of a related object in their response properties. For example, an Application may have an associated Unit ID. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation. This parameter is available on all API requests, and applies to the response of that request only.

You can expand multiple objects at once by identifying multiple items in the expand array.

Core Resources

Enquiries

An enquiry contains information about a prospects interest in applying for a tenancy.

Endpoints

POST      /v1/enquiries
POST      /v1/enquiries/:id
GET       /v1/enquiries/:id
GET       /v1/enquiries
DELETE    /v1/enquiries/:id
POST      /v1/enquiries/:id/decline

The enquiry object

Example Response

{
  "id": "cGLN6RAHFSZf",
  "object": "enquiry",
  "created": 1553097567,
  "assignee": null,
  "buildings": [],
  "declined_reason": null,
  "declined_reason_description": null,
  "description": "Looking for a 2 bedroom flat with 2 bathrooms",
  "email": "[email protected]",
  "first_name": "Jane",
  "follow_up": null,
  "last_name": "Doe",
  "metadata": {},
  "phone": "+44719458928",
  "referral": {
    "source": null,
    "medium": null,
    "campaign": null
  },
  "requirements": {
    "bedrooms": 2,
    "budget_min": 1000,
    "budget_max": 1800,
    "furnished": null,
    "move_in_date": 1553097567,
    "length_of_stay": null,
    "pet_friendly": null,
    "right_to_rent": null,
    "type": null
  },
  "source": "api_key",
  "status": "pending",
  "status_transitions": {
    "application_completed_at": null,
    "application_created_at": null,
    "declined_at": null,
    "first_response_at": null,
    "viewing_created_at": null
  }
}

ATTRIBUTES

id
string
Unique identifier for the object.
object
string
String representing the object’s type. Objects of the same type share the same value.
created
timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
assigned_to
string
Unique identifier of the user the enquiry is currently assigned to.
declined_reason
string
The reason the enquiry was declined. Can be affordability, no_response, not_suitable, no_units, other.
declined_reason_description
string
An arbitrary string useful for displaying additional information about the decline reason.
description
string
An arbitrary string attached to the object. Often useful for displaying additional information.
email
string
Email address of the enquirer.
first_name
string
String representing the first name of the enquirer.
follow_up
timestamp
Time at which a follow up should be made. Measured in seconds since the Unix epoch.
last_name
string
String representing the last name of the enquirer.
metadata
hash
Set of key-value pairs that you can attach to an object. This is useful if you want to store additional data on the object.
phone
string
Optional phone number.
requirements
hash
Object containing key-value pairs describing the requirements of the enquirer.
requirements.bedrooms integer
The required number of bedrooms.
requirements.budget_max integer
The maximum budget.
requirements.budget_min integer
The minimum budget.
requirements.furnished boolean
Whether or not the enquirer wants a furnished property.
requirements.move_in_date timestamp
The desired move-in date.
requirements.length_of_stay string
The desired length of stay.
requirements.pet_friendly boolean
Whether or not the enquirer wants a pet friendly property.
requirements.right_to_rent string
The enquirer's right-to-rent status. Can be not_provided, provided, certified.
requirements.type string
The type of enquiry. Can be residential, student, commercial.
status
string
The status of the enquiry. Can be pending, contacted, declined.
status_transitions
hash
Object containing key-value pairs describing status changes.
status_transitions.application_completed_at timestamp
Time at which the application was completed. Measured in seconds since the Unix epoch.
status_transitions.application_created_at timestamp
Time at which the application was created. Measured in seconds since the Unix epoch.
status_transitions.declined_at timestamp
Time at which the enquiry was declined. Measured in seconds since the Unix epoch.
status_transitions.first_response_at timestamp
Time at which the first response occurred. Measured in seconds since the Unix epoch.
status_transitions.viewing_created_at timestamp
Time at which the first viewing was created. Measured in seconds since the Unix epoch.

Create an enquiry

To create an enquiry, you create an enquiry object. You can create enquiries with either your publishable or secret API key.

Post /v1/enquiries

Example Request

curl https://api.yorlet.com/v1/enquiries
  -H "Authorization: Bearer {API_KEY}"
  -d '{
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe"
      }'

Example Response

{
  "id": "cGLN6RAHFSZf",
  "object": "enquiry",
  "created": 1553097567,
  "assigned_to": null,
  "buildings": [],
  "declined_reason": null,
  "declined_reason_description": null,
  "description": "Looking for a 2 bedroom flat with 2 bathrooms",
  "email": "[email protected]",
  "first_name": "Jane",
  "follow_up": null,
  "last_name": "Doe",
  "metadata": {},
  "phone": "+44719458928",
  "requirements": {
    "bedrooms": 2,
    "budget_min": 1000,
    "budget_max": 1800,
    "furnished": null,
    "move_in_date": 1553097567,
    "length_of_stay": null,
    "pet_friendly": null,
    "right_to_rent": null,
    "type": null
  },
  "source": "session",
  "status": "pending",
  "status_transitions": {
    "application_completed_at": null,
    "application_created_at": null,
    "declined_at": null,
    "first_response_at": null,
    "viewing_created_at": null
  }
}

ARGUMENTS

email
required
Email address of the enquirer.
building
optional
String representing a building ID to associate with the enquiry.
description
optional
An arbitrary string attached to the object. Often useful for displaying additional information.
first_name
optional
String representing the first name of the enquirer.
follow_up
optional
Time at which a follow up should be made. Measured in seconds since the Unix epoch.
last_name
optional
String representing the last name of the enquirer.
metadata
optional
Set of key-value pairs that you can attach to an object. This is useful if you want to store additional data on the object.
phone
optional
Optional phone number.
requirements
optional
Object containing key-value pairs describing the requirements.
requirements.bedrooms integer
The required number of bedrooms.
requirements.budget_max integer
The maximum budget.
requirements.budget_min integer
The minimum budget.
requirements.furnished boolean
Whether or not the enquirer wants a furnished property.
requirements.move_in_date timestamp
The desired move-in date.
requirements.length_of_stay string
The desired length of stay.
requirements.pet_friendly boolean
Whether or not the enquirer wants a pet friendly property.
requirements.right_to_rent string
The enquirer's right-to-rent status. Can be not_provided, provided, certified.
requirements.type string
The type of enquiry. Can be residential, student, commercial.

Update an enquiry

Updates an enquiry that was previously created.

Post /v1/enquiry/:id

Example Request

curl https://api.yorlet.com/v1/enquiries/cGLN6RAHFSZf
  -H "Authorization: Bearer {API_KEY}"
  -d '{
        "first_name": "Jane",
        "phone": "+44773123456"
      }'

Example Response

{
  "id": "cGLN6RAHFSZf",
  "object": "enquiry",
  "created": 1553097567,
  "assigned_to": null,
  "buildings": [],
  "declined_reason": null,
  "declined_reason_description": null,
  "description": "Looking for a 2 bedroom flat with 2 bathrooms",
  "email": "[email protected]",
  "first_name": "Jane",
  "follow_up": null,
  "last_name": "Doe",
  "metadata": {},
  "phone": "+44719458928",
  "requirements": {
    "bedrooms": 2,
    "budget_min": 1000,
    "budget_max": 1800,
    "furnished": null,
    "move_in_date": 1553097567,
    "length_of_stay": null,
    "pet_friendly": null,
    "right_to_rent": null,
    "type": null
  },
  "source": "session",
  "status": "pending",
  "status_transitions": {
    "application_completed_at": null,
    "application_created_at": null,
    "declined_at": null,
    "first_response_at": null,
    "viewing_created_at": null
  }
}

ARGUMENTS

description
optional
An arbitrary string attached to the object. Often useful for displaying additional information.
email
optional
Email address of the enquirer.
first_name
optional
String representing the first name of the enquirer.
follow_up
optional
Time at which a follow up should be made. Measured in seconds since the Unix epoch.
last_name
optional
String representing the last name of the enquirer.
metadata
optional
Set of key-value pairs that you can attach to an object. This is useful if you want to store additional data on the object.
phone
optional
Optional phone number.
requirements
optional
Object containing key-value pairs describing the requirements.
status
optional
The status of the enquiry. Can be pending, contacted, lost.

Retrieve an enquiry

Retrieves the details of the enquiry that has previously been created. Supply the unique enquiry ID that was returned from your previous request.

Get /v1/enquiries/:id

Example Request

curl https://api.yorlet.com/v1/enquiries/cGLN6RAHFSZf
  -H "Authorization: Bearer {API_KEY}"
  -G

Example Response

{
  "id": "cGLN6RAHFSZf",
  "object": "enquiry",
  "created": 1553097567,
  "assigned_to": null,
  "buildings": [],
  "declined_reason": null,
  "declined_reason_description": null,
  "description": "Looking for a 2 bedroom flat with 2 bathrooms",
  "email": "[email protected]",
  "first_name": "Jane",
  "follow_up": null,
  "last_name": "Doe",
  "metadata": {},
  "phone": "+44719458928",
  "requirements": {
    "bedrooms": 2,
    "budget_min": 1000,
    "budget_max": 1800,
    "furnished": null,
    "move_in_date": 1553097567,
    "length_of_stay": null,
    "pet_friendly": null,
    "right_to_rent": null,
    "type": null
  },
  "source": "session",
  "status": "pending",
  "status_transitions": {
    "application_completed_at": null,
    "application_created_at": null,
    "declined_at": null,
    "first_response_at": null,
    "viewing_created_at": null
  }
}

ARGUMENTS

enquiry
required
The identifier of the enquiry to be retrieved.

Returns

Returns an enquiry if a valid identifier was provided, and returns an error otherwise.

List all enquiries

Returns a list of enquiries previously created. The enquiries are returned in sorted order, with the most recent enquiries appearing first.

Get /v1/enquiries

Example Request

curl https://api.yorlet.com/v1/enquiries
  -H "Authorization: Bearer {API_KEY}"
  -G

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "cGLN6RAHFSZf",
      "object": "enquiry",
      "created": 1553097567,
      "assigned_to": null,
      "buildings": [],
      "declined_reason": null,
      "declined_reason_description": null,
      "description": "Looking for a 2 bedroom flat with 2 bathrooms",
      "email": "[email protected]",
      "first_name": "Jane",
      "follow_up": null,
      "last_name": "Doe",
      "metadata": {},
      "phone": "+44719458928",
      "requirements": {
        "bedrooms": 2,
        "budget_min": 1000,
        "budget_max": 1800,
        "furnished": null,
        "move_in_date": 1553097567,
        "length_of_stay": null,
        "pet_friendly": null,
        "right_to_rent": null,
        "type": null
      },
      "source": "session",
      "status": "pending",
      "status_transitions": {
        "application_completed_at": null,
        "application_created_at": null,
        "declined_at": null,
        "first_response_at": null,
        "viewing_created_at": null
      }
    }
  ],
  "count": 1,
  "has_more": false
}

ARGUMENTS

limit
optional
A limit on the number of objects to be returned. Limit can range between 1 and 50, and the default is 20.
offset
optional
A cursor for use in pagination. Used to fetch the next list.

Returns

A dictionary with a data property that contains an array of up to a limit, starting after the offset if provided. Each entry in the array is a separate enquiry object. If no more enquiries are available, the resulting array will be empty.

Delete an enquiry

Delete an enquiry that was previously created.

Delete /v1/enquiries/:id

Example Request

curl https://api.yorlet.com/v1/enquiries/OgkcIZ5AokR8
  -H "Authorization: Bearer {API_KEY}"
  -G

Example Response

{
  "id": "cGLN6RAHFSZf",
  "object": "enquiry",
  "deleted": true
}

ARGUMENTS

enquiry
required
The identifier of the enquiry to be retrieved.

Returns

An enquiry object marked as deleted.

Decline an enquiry

Decline an enquiry that was previously created.

Delete /v1/enquiries/:id/decline

Example Request

curl https://api.yorlet.com/v1/enquiries/OgkcIZ5AokR8/decline
  -H "Authorization: Bearer {API_KEY}"
  -d '{
        "declined_reason": "other",
      }'

Example Response

{
  "id": "cGLN6RAHFSZf",
  "object": "enquiry",
  "created": 1553097567,
  "assigned_to": null,
  "buildings": [],
  "declined_reason": "other",
  "declined_reason_description": null,
  "description": "Looking for a 2 bedroom flat with 2 bathrooms",
  "email": "[email protected]",
  "first_name": "Jane",
  "follow_up": null,
  "last_name": "Doe",
  "metadata": {},
  "phone": "+44719458928",
  "requirements": {
    "bedrooms": 2,
    "budget_min": 1000,
    "budget_max": 1800,
    "furnished": null,
    "move_in_date": 1553097567,
    "length_of_stay": null,
    "pet_friendly": null,
    "right_to_rent": null,
    "type": null
  },
  "source": "session",
  "status": "declined",
  "status_transitions": {
    "application_completed_at": null,
    "application_created_at": null,
    "declined_at": null,
    "first_response_at": null,
    "viewing_created_at": null
  }
}

ARGUMENTS

enquiry
required
The identifier of the enquiry to be retrieved.
declined_reason
optional
The reason the enquiry was declined. Can be affordability, no_response, not_suitable, no_units, other.
declined_reason_description
optional
An arbitrary string useful for displaying additional information about the decline reason.

Returns

An updated enquiry object with a declined status.