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.

Idempotency

Example Request

curl https://api.yorlet.com/v1/enquiries
  -H "Authorization: Bearer {access_token}"
  -H "Idempotency-Key: {unique_key}"

The Yorlet API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a new enquiry does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one enquiry is created.

To perform an idempotent request, provide an additional Idempotency-Key element to the request options.

Yorlet's idempotency architecture works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognise subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Keys expire after 24 hours, so a new request is generated if a key is reused outside of that time frame. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.


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.