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.

Environments

Our API and Dashboard are available in two environments:

Authentication

Authenticated request

curl https://api.yorlet.com/v1/applications \
-H "Authorization: Bearer {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 API key should be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer {API_KEY}

Errors

The error object

{
  "error": {
    "message": "The supplied customer was not found.",
    "param": "customer",
    "type": "invalid_request"
  },
  "status": 404
}

Yorlet uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Yorlet's servers.

Attributes

• error object

  The error object.

  error.message string

  A human-readable message providing more details about the error.

  error.param string

  If the error is parameter-specific, the parameter related to the error.

  error.type string

  The type of error returned.
• status integer

  The status code.

Expanding Objects

Application with expanded unit

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

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

Request with idempotency

curl https://api.yorlet.com/v1/customers
  -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 header.

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

Applications

Endpoints

POST    /v1/applications
GET     /v1/applications/:id
POST    /v1/applications/:id
POST    /v1/applications/:id/accept
POST    /v1/applications/:id/cancel
POST    /v1/applications/:id/complete
GET     /v1/applications

Application objects allow you to create new leases, accept move-in payments and set up contracts. The API allows you to create, delete, and update your applications. You can retrieve individual applications as well as a list of all your applications.

The application object

The application object

{
  "id": "app_test",
  "object": "application",
  "created": 1627210800,
  "account_collection_data": null,
  "applicant_requests": null,
  "auto_apply_unit_fees": false,
  "break_clause": {
    "notification_date": null,
    "terms": null
  },
  "building": null,
  "building_snapshot": {},
  "cancel_reason": null,
  "cancel_reason_description": null,
  "contract": null,
  "checkin_time": null,
  "checkout_time": null,
  "completed_at": null,
  "completion_behavior": "automatic",
  "contract_address": null,
  "contract_legal_entity": null,
  "contract_template": null,
  "create_contract_on_accept": false,
  "currency": "gbp",
  "customer_emails": [],
  "customers": [],
  "date_end": null,
  "date_start": null,
  "deposit": {},
  "description": null,
  "end_behavior": null,
  "enquiry": null,
  "has_owner": false,
  "holding_fee_required": false,
  "metadata": {},
  "move_in_date": null,
  "move_out_date": null,
  "open": false,
  "owner_signature_required": false,
  "post_application_payment_session": null,
  "renewal_intent": null,
  "rent_term": null,
  "send_owner_contract": false,
  "subscription_data": null,
  "status": null,
  "tenancy_created": false,
  "tenancy_timestamp": null,
  "type": "standard",
  "unit": null,
  "unit_snapshot": {
    "epc_file": null,
    "name": 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. Can be application.
• created timestamp

  Time at which the object was created. Measured in seconds since the Unix epoch.
• account_collection_data object

  The account collection data for the application.
• advance_rent integer

  The amount of advance rent to be paid.
• applicant_requests string

  The applicant requests on the application.
• auto_apply_unit_fees string

  Whether or not to apply unit fees to owner records after the application completes.
• break_clause object

  The break clause for the application.
• building stringexpandable

  The building the application is for.
• building_snapshot object

  The snapshot of the building at the time of application.
• cancel_reason string

  The reason for cancelling the application.
• cancel_reason_description string

  The description for cancelling the application.
• contract stringexpandable

  The contract for the application.
• checkin_time string

  The checkin time for the application.
• checkout_time string

  The checkout time for the application.
• completed_at timestamp

  Measured in seconds since the Unix epoch.
• completion_behavior string

  The completion behavior for the application.
• contract_address string

  The address of the contract for the application.
• contract_legal_entity string

  The legal entity for the contract, if provided this replaces the owner.
• contract_template stringexpandable

  The contract template for the application.
• create_contract_on_accept boolean

  Whether or not to create a contract on acceptance.
• currency string

  The currency for the application.
• customer_emails array

  The customer emails for the application.
• customers array

  The customers for the application.
• date_end timestamp

  Measured in seconds since the Unix epoch.
• date_start timestamp

  Measured in seconds since the Unix epoch.
• deposit object

  The deposit for the application.
• description string

  An arbitrary string attached to the object. Often useful for displaying to users.
• end_behavior string

  The end behavior for the application. Can be complete or roll.
• enquiry string

  The enquiry for the application.
• has_owner boolean

  Whether or not the application has an owner.
• holding_fee object

  The amount of holding fee to be paid.
• holding_fee_required boolean

  Whether or not the application requires a holding fee.
• metadata string

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• move_in_date timestamp

  The date the tenant is expected to move in. Useful for short term lets where the actual move in date may differ from the contractual move in date. Measured in seconds since the Unix epoch.
• move_out_date timestamp

  The date the tenant is expected to move out. Useful for short term lets where the actual move out date may differ from the contractual move out date. Measured in seconds since the Unix epoch.
• open boolean

  Whether or not the application is open.
• owner_signature_required boolean

  Whether or not the owner signature is required.
• post_application_payment_session object

  The payment session data for the application. If set this creates a payment session after the contract is signed.
• renewal_intent stringexpandable

  The renewal intent for the application.
• rent_term string

  The rent term for the application.
• send_owner_contract boolean

  Whether or not to send the owner contract.
• subscription_data object

  The subscription data for the application.
• status string

  The status of the application.
• tenancy_created boolean

  Whether or not the tenancy has been created.
• tenancy_timestamp timestamp

  Measured in seconds since the Unix epoch.
• type string

  The type of the application.
• unit stringexpandable

  The unit for the application.
• unit_snapshot object

  The unit snapshot at the time of application.

  unit_snapshot.epc_file string

  The EPC file for the unit.

  unit_snapshot.name string

  The name of the unit.

Create an application

POST /v1/applications

curl https://api.yorlet.com/v1/applications \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "email": "[email protected]"
}'

Example Response

{
  "id": "app_test",
  "object": "application",
  "created": 1627210800,
  "account_collection_data": null,
  "applicant_requests": null,
  "auto_apply_unit_fees": false,
  "break_clause": {
    "notification_date": null,
    "terms": null
  },
  "building": null,
  "building_snapshot": {},
  "cancel_reason": null,
  "cancel_reason_description": null,
  "contract": null,
  "checkin_time": null,
  "checkout_time": null,
  "completed_at": null,
  "completion_behavior": "automatic",
  "contract_address": null,
  "contract_legal_entity": null,
  "contract_template": null,
  "create_contract_on_accept": false,
  "currency": "gbp",
  "customer_emails": [],
  "customers": [],
  "date_end": null,
  "date_start": null,
  "deposit": {},
  "description": null,
  "end_behavior": null,
  "enquiry": null,
  "has_owner": false,
  "holding_fee_required": false,
  "metadata": {},
  "move_in_date": null,
  "move_out_date": null,
  "open": false,
  "owner_signature_required": false,
  "post_application_payment_session": null,
  "renewal_intent": null,
  "rent_term": null,
  "send_owner_contract": false,
  "subscription_data": null,
  "status": null,
  "tenancy_created": false,
  "tenancy_timestamp": null,
  "type": "standard",
  "unit": null,
  "unit_snapshot": {
    "epc_file": null,
    "name": null
  }
}

Creates a new application.

Parameters

• applicants required  array of objects

  The applicants.

  applicants.share_of_rent required  number

  The applicant's share of the rent.

  applicants.create_reference boolean

  Whether to create a reference for the applicant.

  applicants.customer string

  The customer ID of the applicant.

  applicants.customer_data object

  The customer data of the applicant. Must be supplied if customer ID is not provided.

  applicants.customer_data.email required  string

  The email address of the customer.

  applicants.customer_data.legal object

  The customer's legal information. Used for generating contracts.

  applicants.customer_data.legal.first_name required  string

  The customer's full legal firstname.

  applicants.customer_data.legal.last_name required  string

  The customer's full legal lastname.

  applicants.customer_data.legal.dob object

  The customer's date of birth

  applicants.customer_data.legal.dob.day required  integer

  The customer's day of birth

  applicants.customer_data.legal.dob.month required  integer

  The customer's month of birth

  applicants.customer_data.legal.dob.year required  integer

  The customer's year of birth

  applicants.customer_data.name string

  The customer's full name.

  applicants.customer_data.phone string

  The customer's phone number.

  applicants.lead_tenant boolean

  Whether the applicant is the lead tenant.

  applicants.permitted_occupier boolean

  Whether the applicant is a permitted occupier.

  applicants.reference_data object

  The applicant's reference data.

  applicants.reference_data.automatic_reference object

  applicants.reference_data.automatic_reference.enabled required  boolean

  Whether to enable automatic references.

  applicants.reference_data.automatic_reference.provider required  string

  The reference provider. Can be canopy.
• end_date required  timestamp

  The end date of the tenancy. When null the tenancy will roll periodically.
• start_date required  timestamp

  The start date of the tenancy.
• subscription_data required  object

  The subscription data for the subscription.

  subscription_data.collection_method required  string

  The collection method for the subscription. Can be charge_automatically or send_invoice.

  subscription_data.interval required  string

  The interval of the subscription. Can be month, week, custom or upfront.

  subscription_data.interval_count required  integer

  The interval count of the subscription.

  subscription_data.add_invoice_items array of objects

  A list of up to 10 invoice items that will be appended to the next invoice for this subscription.

  subscription_data.add_invoice_items.type required  string

  The type of subscription item. Can be rent, charge or product.

  subscription_data.add_invoice_items.description string

  Description for the subscription item.

  subscription_data.add_invoice_items.metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  subscription_data.add_invoice_items.price string

  The ID of the price object.

  subscription_data.add_invoice_items.price_data object

  The price data for the subscription item.

  subscription_data.add_invoice_items.price_data.amount required  integer

  A positive integer in pence representing how much to charge.

  subscription_data.add_invoice_items.price_data.currency required  string

  Three-letter ISO currency code, in lowercase.

  subscription_data.add_invoice_items.price_data.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.add_invoice_items.proration_behavior string

  Can be create_prorations or none.

  subscription_data.add_invoice_items.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.add_invoice_items.transfer_behavior string

  Can be automatic, owner or none.

  subscription_data.add_invoice_items.transfer_destination string

  ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

  subscription_data.add_invoice_items.unit string

  The ID of the unit. If type=rent you must provide a unit ID

  subscription_data.billing_anchor timestamp

  The date to anchor the subscription to.

  subscription_data.coupon string

  The ID of the coupon to apply to the subscription.

  subscription_data.days_before_collection integer

  The number of days to create the invoice before the subscription's next billing date. Useful if you want to send the customer the upcoming invoice a few days before the subscription's next billing date. Only applies to subscriptions with collection_method=send_invoice.

  subscription_data.days_until_due integer

  The number of days before the invoice is due.

  subscription_data.end_date timestamp

  The date this subscription should end. When a subscription ends the status will change to complete

  subscription_data.items array of objects

  A list of up to 10 subscription items, each with attached price_data.

  subscription_data.items.type required  string

  The type of subscription item. Can be rent, charge or product.

  subscription_data.items.description string

  Description for the subscription item.

  subscription_data.items.metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  subscription_data.items.price string

  The ID of the price object.

  subscription_data.items.price_data object

  The price data for the subscription item.

  subscription_data.items.price_data.amount required  integer

  A positive integer in pence representing how much to charge.

  subscription_data.items.price_data.currency required  string

  Three-letter ISO currency code, in lowercase.

  subscription_data.items.price_data.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.items.proration_behavior string

  Can be create_prorations or none.

  subscription_data.items.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.items.transfer_behavior string

  Can be automatic, owner or none.

  subscription_data.items.transfer_destination string

  ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

  subscription_data.items.unit string

  The ID of the unit. If type=rent you must provide a unit ID

  subscription_data.phases array of objects

  The phases of the subscription. Only allowed when interval=custom.

  subscription_data.phases.start_date required  timestamp

  The date on which the phase starts.

  subscription_data.phases.items array of objects

  A list of up to 10 subscription items, each with attached price_data.

  subscription_data.phases.items.type required  string

  The type of subscription item. Can be rent, charge or product.

  subscription_data.phases.items.description string

  Description for the subscription item.

  subscription_data.phases.items.metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  subscription_data.phases.items.price string

  The ID of the price object.

  subscription_data.phases.items.price_data object

  The price data for the subscription item.

  subscription_data.phases.items.price_data.amount required  integer

  A positive integer in pence representing how much to charge.

  subscription_data.phases.items.price_data.currency required  string

  Three-letter ISO currency code, in lowercase.

  subscription_data.phases.items.price_data.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.phases.items.proration_behavior string

  Can be create_prorations or none.

  subscription_data.phases.items.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.phases.items.transfer_behavior string

  Can be automatic, owner or none.

  subscription_data.phases.items.transfer_destination string

  ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

  subscription_data.phases.items.unit string

  The ID of the unit. If type=rent you must provide a unit ID

  subscription_data.start_date timestamp

  The date this subscription should begin. Start dates in the future will cause the initial status of the sunscription to be scheduled
• type required  string

  The application type. Can be standard, active_tenancy, renewal or let_only.
• unit required  string

  The unit ID.
• accept boolean

  Set to true to attempt to accept this application immediately. The parameter defaults to false and is only allowed when type=active_tenancy.
• account_collection_data object

  The account collection data, this overwrites any existing unit fees.

  account_collection_data.amount required  integer

  The amount to charge.
• advance_rent integer

  The amount of advance rent to charge.
• applicant_requests string

  The applicant special requests.
• auto_apply_unit_fees boolean

  Whether to automatically apply the unit's fees.
• automatic_deposit_registration object

  automatic_deposit_registration.branch_id string

  automatic_deposit_registration.scheme string

  automatic_deposit_registration.scheme_type string
• break_clause object

  The break clause data.

  break_clause.notification_date timestamp

  The break clause notification date.

  break_clause.terms string

  The break clause terms.
• checkin_time string

  The checkin time.
• checkout_time string

  The checkout time.
• completion_behavior string

  The completion behavior for the application. Can be automatic or manual.
• contract string

  The contract's ID.
• contract_address string

  The contract address. Passing this field will update the contract address on the selected unit record.
• contract_legal_entity string

  The legal entity for the contract, if provided this replaces the owner legal details.
• create_contract_on_accept boolean

  Whether to create a contract when the application is accepted.
• create_deposit boolean

  Whether to create a deposit object when the deposit payments have been collected.
• currency string

  Three-letter ISO currency code, in lowercase.
• deposit integer

  The deposit amount.
• deposit_data object

  The deposit data for the application.

  deposit_data.automatic_deposit object

  The automatic deposit hash.

  deposit_data.automatic_deposit.branch_id string

  The ID of the branch to use for the deposit.

  deposit_data.automatic_deposit.enabled boolean

  Whether to enable automatic deposits.

  deposit_data.handled_externally boolean

  Whether the deposit is handled externally or not. Usually this means the landlord or a thrid party has registered the deposit and will handle it.

  deposit_data.scheme object

  The deposit scheme information.

  deposit_data.scheme.provider required  string

  The deposit provider. Can be dps, mydeposits or tds.

  deposit_data.scheme.type required  string

  The deposit type. Can be custodial or insured.
• end_behavior string

  The end behavior for the application. If there is a end date set at the end of the tenancy, complete will ensure that the tenancy is marked as complete, roll will ensure that the tenancy starts to roll periodically. Only allowed if end_date is set.
• enquiry string

  The enquiry's ID.
• holding_fee integer

  The holding fee amount.
• insurance object

  insurance.rent_protection object

  insurance.rent_protection.automatic boolean

  Whether to enable automatic rent protection.

  insurance.rent_protection.provider string

  The rent protection provider. Can be alan_boswell.
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• move_in_date timestamp

  The date the tenant is expected to move in. Useful for short term lets where the actual move in date may differ from the contractual move in date.
• move_out_date timestamp

  The date the tenant is expected to move out. Useful for short term lets where the actual move out date may differ from the contractual move out date.
• owner_signature_required boolean

  Whether the owner signature is required.
• post_application_payment_session object

  The payment session data for the application.

  post_application_payment_session.amount required  integer

  The amount to charge.

  post_application_payment_session.description required  string

  The description of the payment session.

  post_application_payment_session.payment_method_types required  array of strings

  Can be one or many of autogiro, bacs_debit, bank_transfer, card, direct_transfer, pay_by_bank or sepa_debit.

  post_application_payment_session.reporting_type string

  The reporting type of the transaction. Defaults to charge. Can be advance_rent, charge, deposit, holding_fee or rent.
• renewal_days_before_end integer

  The number of days before the end of the tenancy to renew it.
• renewal_intent string

  The renewal intent to create this application with.
• send_email boolean

  Whether to send emails to the applicants.
• send_owner_contract boolean

  Whether to send the owner the contract on completion.

Returns

Returns the application object if the request succeeded.

Retrieve an application

GET /v1/applications/:id

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

Example Response

{
  "id": "app_test",
  "object": "application",
  "created": 1627210800,
  "account_collection_data": null,
  "applicant_requests": null,
  "auto_apply_unit_fees": false,
  "break_clause": {
    "notification_date": null,
    "terms": null
  },
  "building": null,
  "building_snapshot": {},
  "cancel_reason": null,
  "cancel_reason_description": null,
  "contract": null,
  "checkin_time": null,
  "checkout_time": null,
  "completed_at": null,
  "completion_behavior": "automatic",
  "contract_address": null,
  "contract_legal_entity": null,
  "contract_template": null,
  "create_contract_on_accept": false,
  "currency": "gbp",
  "customer_emails": [],
  "customers": [],
  "date_end": null,
  "date_start": null,
  "deposit": {},
  "description": null,
  "end_behavior": null,
  "enquiry": null,
  "has_owner": false,
  "holding_fee_required": false,
  "metadata": {},
  "move_in_date": null,
  "move_out_date": null,
  "open": false,
  "owner_signature_required": false,
  "post_application_payment_session": null,
  "renewal_intent": null,
  "rent_term": null,
  "send_owner_contract": false,
  "subscription_data": null,
  "status": null,
  "tenancy_created": false,
  "tenancy_timestamp": null,
  "type": "standard",
  "unit": null,
  "unit_snapshot": {
    "epc_file": null,
    "name": null
  }
}

Retrieves the application with the given ID.

Parameters

• No parameters

Returns

Returns an application object if a valid identifier was provided.

Update an application

POST /v1/applications/:id

curl https://api.yorlet.com/v1/applications/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "app_test",
  "object": "application",
  "created": 1627210800,
  "account_collection_data": null,
  "applicant_requests": null,
  "auto_apply_unit_fees": false,
  "break_clause": {
    "notification_date": null,
    "terms": null
  },
  "building": null,
  "building_snapshot": {},
  "cancel_reason": null,
  "cancel_reason_description": null,
  "contract": null,
  "checkin_time": null,
  "checkout_time": null,
  "completed_at": null,
  "completion_behavior": "automatic",
  "contract_address": null,
  "contract_legal_entity": null,
  "contract_template": null,
  "create_contract_on_accept": false,
  "currency": "gbp",
  "customer_emails": [],
  "customers": [],
  "date_end": null,
  "date_start": null,
  "deposit": {},
  "description": null,
  "end_behavior": null,
  "enquiry": null,
  "has_owner": false,
  "holding_fee_required": false,
  "metadata": {},
  "move_in_date": null,
  "move_out_date": null,
  "open": false,
  "owner_signature_required": false,
  "post_application_payment_session": null,
  "renewal_intent": null,
  "rent_term": null,
  "send_owner_contract": false,
  "subscription_data": null,
  "status": null,
  "tenancy_created": false,
  "tenancy_timestamp": null,
  "type": "standard",
  "unit": null,
  "unit_snapshot": {
    "epc_file": null,
    "name": null
  }
}

Updates the specified application by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

• account_collection_data object

  The account collection data, this overwrites any existing unit fees.

  account_collection_data.amount required  integer

  The amount to charge.
• advance_rent integer

  The amount of advance rent to charge.
• applicant_requests string

  The applicant special requests.
• auto_apply_unit_fees boolean

  Whether to automatically apply the unit's fees.
• automatic_deposit_registration object

  automatic_deposit_registration.branch_id string

  automatic_deposit_registration.scheme string

  automatic_deposit_registration.scheme_type string
• break_clause object

  The break clause data.

  break_clause.notification_date timestamp

  The break clause notification date.

  break_clause.terms string

  The break clause terms.
• checkin_time string

  The checkin time.
• checkout_time string

  The checkout time.
• contract_address string

  The contract address. Passing this field will update the contract address on the selected unit record.
• contract_legal_entity string

  The legal entity for the contract, if provided this replaces the owner legal details.
• contract_template string

  The ID of the contract template.
• create_deposit boolean

  Whether to create a deposit object when the deposit payments have been collected.
• currency string

  Three-letter ISO currency code, in lowercase.
• deposit integer

  The deposit amount.
• deposit_data object

  The deposit data for the application.

  deposit_data.automatic_deposit object

  The automatic deposit hash.

  deposit_data.automatic_deposit.branch_id string

  The ID of the branch to use for the deposit.

  deposit_data.automatic_deposit.enabled boolean

  Whether to enable automatic deposits.

  deposit_data.handled_externally boolean

  Whether the deposit is handled externally or not. Usually this means the landlord or a thrid party has registered the deposit and will handle it.

  deposit_data.scheme object

  The deposit scheme information.

  deposit_data.scheme.provider required  string

  The deposit provider. Can be dps, mydeposits or tds.

  deposit_data.scheme.type required  string

  The deposit type. Can be custodial or insured.
• end_behavior string

  The end behavior for the application. If there is a end date set at the end of the tenancy, complete will ensure that the tenancy is marked as complete, roll will ensure that the tenancy starts to roll periodically. Only allowed if end_date is set.
• end_date timestamp

  The end date of the tenancy. When null the tenancy will roll periodically.
• insurance object

  insurance.rent_protection object

  insurance.rent_protection.automatic boolean

  Whether to enable automatic rent protection.

  insurance.rent_protection.provider string

  The rent protection provider. Can be alan_boswell.
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• move_in_date timestamp

  The date the tenant is expected to move in. Useful for short term lets where the actual move in date may differ from the contractual move in date.
• move_out_date timestamp

  The date the tenant is expected to move out. Useful for short term lets where the actual move out date may differ from the contractual move out date.
• owner_signature_required boolean

  Whether the owner signature is required.
• post_application_payment_session object

  The payment session data for the application.

  post_application_payment_session.amount required  integer

  The amount to charge.

  post_application_payment_session.description required  string

  The description of the payment session.

  post_application_payment_session.payment_method_types required  array of strings

  Can be one or many of autogiro, bacs_debit, bank_transfer, card, direct_transfer, pay_by_bank or sepa_debit.

  post_application_payment_session.reporting_type string

  The reporting type of the transaction. Defaults to charge. Can be advance_rent, charge, deposit, holding_fee or rent.
• renewal_days_before_end integer

  The number of days before the end of the tenancy to renew it.
• renewal_intent string

  The renewal intent to create this application with.
• send_owner_contract boolean

  Whether to send the owner the contract on completion.
• share_of_rent array of objects

  share_of_rent.applicant required  string

  share_of_rent.guarantor_required required  boolean

  share_of_rent.lead_tenant required  boolean

  share_of_rent.percentage required  number

  share_of_rent.permitted_occupier required  boolean
• start_date timestamp

  The start date of the tenancy.
• status string

  Sometimes it is useful to change the status to generate a contract. This is only allowed if the application does not already have a contract. Can be pending_contract_generation.
• subscription_data object

  The subscription data for the subscription.

  subscription_data.collection_method required  string

  The collection method for the subscription. Can be charge_automatically or send_invoice.

  subscription_data.interval required  string

  The interval of the subscription. Can be month, week, custom or upfront.

  subscription_data.interval_count required  integer

  The interval count of the subscription.

  subscription_data.add_invoice_items array of objects

  A list of up to 10 invoice items that will be appended to the next invoice for this subscription.

  subscription_data.add_invoice_items.type required  string

  The type of subscription item. Can be rent, charge or product.

  subscription_data.add_invoice_items.description string

  Description for the subscription item.

  subscription_data.add_invoice_items.metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  subscription_data.add_invoice_items.price string

  The ID of the price object.

  subscription_data.add_invoice_items.price_data object

  The price data for the subscription item.

  subscription_data.add_invoice_items.price_data.amount required  integer

  A positive integer in pence representing how much to charge.

  subscription_data.add_invoice_items.price_data.currency required  string

  Three-letter ISO currency code, in lowercase.

  subscription_data.add_invoice_items.price_data.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.add_invoice_items.proration_behavior string

  Can be create_prorations or none.

  subscription_data.add_invoice_items.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.add_invoice_items.transfer_behavior string

  Can be automatic, owner or none.

  subscription_data.add_invoice_items.transfer_destination string

  ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

  subscription_data.add_invoice_items.unit string

  The ID of the unit. If type=rent you must provide a unit ID

  subscription_data.billing_anchor timestamp

  The date to anchor the subscription to.

  subscription_data.coupon string

  The ID of the coupon to apply to the subscription.

  subscription_data.days_before_collection integer

  The number of days to create the invoice before the subscription's next billing date. Useful if you want to send the customer the upcoming invoice a few days before the subscription's next billing date. Only applies to subscriptions with collection_method=send_invoice.

  subscription_data.days_until_due integer

  The number of days before the invoice is due.

  subscription_data.end_date timestamp

  The date this subscription should end. When a subscription ends the status will change to complete

  subscription_data.items array of objects

  A list of up to 10 subscription items, each with attached price_data.

  subscription_data.items.type required  string

  The type of subscription item. Can be rent, charge or product.

  subscription_data.items.description string

  Description for the subscription item.

  subscription_data.items.metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  subscription_data.items.price string

  The ID of the price object.

  subscription_data.items.price_data object

  The price data for the subscription item.

  subscription_data.items.price_data.amount required  integer

  A positive integer in pence representing how much to charge.

  subscription_data.items.price_data.currency required  string

  Three-letter ISO currency code, in lowercase.

  subscription_data.items.price_data.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.items.proration_behavior string

  Can be create_prorations or none.

  subscription_data.items.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.items.transfer_behavior string

  Can be automatic, owner or none.

  subscription_data.items.transfer_destination string

  ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

  subscription_data.items.unit string

  The ID of the unit. If type=rent you must provide a unit ID

  subscription_data.phases array of objects

  The phases of the subscription. Only allowed when interval=custom.

  subscription_data.phases.start_date required  timestamp

  The date on which the phase starts.

  subscription_data.phases.items array of objects

  A list of up to 10 subscription items, each with attached price_data.

  subscription_data.phases.items.type required  string

  The type of subscription item. Can be rent, charge or product.

  subscription_data.phases.items.description string

  Description for the subscription item.

  subscription_data.phases.items.metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  subscription_data.phases.items.price string

  The ID of the price object.

  subscription_data.phases.items.price_data object

  The price data for the subscription item.

  subscription_data.phases.items.price_data.amount required  integer

  A positive integer in pence representing how much to charge.

  subscription_data.phases.items.price_data.currency required  string

  Three-letter ISO currency code, in lowercase.

  subscription_data.phases.items.price_data.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.phases.items.proration_behavior string

  Can be create_prorations or none.

  subscription_data.phases.items.tax_percent number

  The percentage of sales tax to charge. For example, VAT would be 20.

  subscription_data.phases.items.transfer_behavior string

  Can be automatic, owner or none.

  subscription_data.phases.items.transfer_destination string

  ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

  subscription_data.phases.items.unit string

  The ID of the unit. If type=rent you must provide a unit ID

  subscription_data.start_date timestamp

  The date this subscription should begin. Start dates in the future will cause the initial status of the sunscription to be scheduled
• unit string

  The unit ID.

Returns

Returns the application object if the update succeeded.

Accept an application

POST /v1/applications/:id/accept

curl https://api.yorlet.com/v1/applications/:id/accept \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "app_test",
  "object": "application",
  "created": 1627210800,
  "account_collection_data": null,
  "applicant_requests": null,
  "auto_apply_unit_fees": false,
  "break_clause": {
    "notification_date": null,
    "terms": null
  },
  "building": null,
  "building_snapshot": {},
  "cancel_reason": null,
  "cancel_reason_description": null,
  "contract": null,
  "checkin_time": null,
  "checkout_time": null,
  "completed_at": null,
  "completion_behavior": "automatic",
  "contract_address": null,
  "contract_legal_entity": null,
  "contract_template": null,
  "create_contract_on_accept": false,
  "currency": "gbp",
  "customer_emails": [],
  "customers": [],
  "date_end": null,
  "date_start": null,
  "deposit": {},
  "description": null,
  "end_behavior": null,
  "enquiry": null,
  "has_owner": false,
  "holding_fee_required": false,
  "metadata": {},
  "move_in_date": null,
  "move_out_date": null,
  "open": false,
  "owner_signature_required": false,
  "post_application_payment_session": null,
  "renewal_intent": null,
  "rent_term": null,
  "send_owner_contract": false,
  "subscription_data": null,
  "status": null,
  "tenancy_created": false,
  "tenancy_timestamp": null,
  "type": "standard",
  "unit": null,
  "unit_snapshot": {
    "epc_file": null,
    "name": null
  }
}

Accepts the specified application.

Parameters

• No parameters

Returns

Returns the updated application object.

Cancel an application

POST /v1/applications/:id/cancel

curl https://api.yorlet.com/v1/applications/:id/cancel \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "app_test",
  "object": "application",
  "created": 1627210800,
  "account_collection_data": null,
  "applicant_requests": null,
  "auto_apply_unit_fees": false,
  "break_clause": {
    "notification_date": null,
    "terms": null
  },
  "building": null,
  "building_snapshot": {},
  "cancel_reason": null,
  "cancel_reason_description": null,
  "contract": null,
  "checkin_time": null,
  "checkout_time": null,
  "completed_at": null,
  "completion_behavior": "automatic",
  "contract_address": null,
  "contract_legal_entity": null,
  "contract_template": null,
  "create_contract_on_accept": false,
  "currency": "gbp",
  "customer_emails": [],
  "customers": [],
  "date_end": null,
  "date_start": null,
  "deposit": {},
  "description": null,
  "end_behavior": null,
  "enquiry": null,
  "has_owner": false,
  "holding_fee_required": false,
  "metadata": {},
  "move_in_date": null,
  "move_out_date": null,
  "open": false,
  "owner_signature_required": false,
  "post_application_payment_session": null,
  "renewal_intent": null,
  "rent_term": null,
  "send_owner_contract": false,
  "subscription_data": null,
  "status": null,
  "tenancy_created": false,
  "tenancy_timestamp": null,
  "type": "standard",
  "unit": null,
  "unit_snapshot": {
    "epc_file": null,
    "name": null
  }
}

Cancels the specified application.

Parameters

• advance_rent_behavior required  string

  Can be none or refund.
• cancel_reason required  string

  Can be requested_by_customer, incorrect_details, reference_failed, right_to_rent, not_suitable, no_units, timing or other.
• deposit_behavior required  string

  Can be none or refund.
• holding_fee_behavior required  string

  Can be recognize_revenue or refund.
• cancel_reason_description string

Returns

Returns the updated application object.

Complete an application

POST /v1/applications/:id/complete

curl https://api.yorlet.com/v1/applications/:id/complete \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "app_test",
  "object": "application",
  "created": 1627210800,
  "account_collection_data": null,
  "applicant_requests": null,
  "auto_apply_unit_fees": false,
  "break_clause": {
    "notification_date": null,
    "terms": null
  },
  "building": null,
  "building_snapshot": {},
  "cancel_reason": null,
  "cancel_reason_description": null,
  "contract": null,
  "checkin_time": null,
  "checkout_time": null,
  "completed_at": null,
  "completion_behavior": "automatic",
  "contract_address": null,
  "contract_legal_entity": null,
  "contract_template": null,
  "create_contract_on_accept": false,
  "currency": "gbp",
  "customer_emails": [],
  "customers": [],
  "date_end": null,
  "date_start": null,
  "deposit": {},
  "description": null,
  "end_behavior": null,
  "enquiry": null,
  "has_owner": false,
  "holding_fee_required": false,
  "metadata": {},
  "move_in_date": null,
  "move_out_date": null,
  "open": false,
  "owner_signature_required": false,
  "post_application_payment_session": null,
  "renewal_intent": null,
  "rent_term": null,
  "send_owner_contract": false,
  "subscription_data": null,
  "status": null,
  "tenancy_created": false,
  "tenancy_timestamp": null,
  "type": "standard",
  "unit": null,
  "unit_snapshot": {
    "epc_file": null,
    "name": null
  }
}

Marks the specified application as complete.

Parameters

• No parameters

Returns

Returns the updated application object.

List all applications

GET /v1/applications

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "app_test",
      "object": "application",
      "created": 1627210800,
      "account_collection_data": null,
      "applicant_requests": null,
      "auto_apply_unit_fees": false,
      "break_clause": {
        "notification_date": null,
        "terms": null
      },
      "building": null,
      "building_snapshot": {},
      "cancel_reason": null,
      "cancel_reason_description": null,
      "contract": null,
      "checkin_time": null,
      "checkout_time": null,
      "completed_at": null,
      "completion_behavior": "automatic",
      "contract_address": null,
      "contract_legal_entity": null,
      "contract_template": null,
      "create_contract_on_accept": false,
      "currency": "gbp",
      "customer_emails": [],
      "customers": [],
      "date_end": null,
      "date_start": null,
      "deposit": {},
      "description": null,
      "end_behavior": null,
      "enquiry": null,
      "has_owner": false,
      "holding_fee_required": false,
      "metadata": {},
      "move_in_date": null,
      "move_out_date": null,
      "open": false,
      "owner_signature_required": false,
      "post_application_payment_session": null,
      "renewal_intent": null,
      "rent_term": null,
      "send_owner_contract": false,
      "subscription_data": null,
      "status": null,
      "tenancy_created": false,
      "tenancy_timestamp": null,
      "type": "standard",
      "unit": null,
      "unit_snapshot": {
        "epc_file": null,
        "name": null
      }
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of applications. The applications are returned sorted by creation date, with the most recent applications appearing first.

Parameters

• building string

  The building ID.
• customer string

  The customer ID.
• customers array of strings

  The customers IDs.
• enquiry string

  The enquiry ID.
• open string

  Whether the application is open.
• status string or array of strings

  The status of the application. Can be one or many of pending, pending_payment_method, pending_acceptance, pending_deposit, pending_guarantor, pending_guarantor_approval, pending_guarantor_contract, pending_guarantor_contract_landlord, pending_contract_generation, pending_contract, pending_contract_landlord, complete, canceled, expired or declined.
• type string

  The type of the application.
• unit string

  The unit ID.

Returns

A object with a data property that contains an array of applications.

Buildings

Endpoints

POST    /v1/buildings
GET     /v1/buildings/:id
POST    /v1/buildings/:id
DELETE  /v1/buildings/:id
GET     /v1/buildings

Building objects are a core resource and allow you to create units. The API allows you to create, delete, and update your buildings. You can retrieve individual buildings as well as a list of all your buildings.

The building object

The building object

{
  "id": "build_test",
  "object": "building",
  "created": 1627210800,
  "accounting_code": null,
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "name": null,
  "single_unit": false,
  "type": null,
  "unit_fees": {
    "management_fee": null,
    "management_fee_amount": null,
    "management_fee_type": "percentage",
    "renewal_fee": null,
    "tax": null,
    "tax_behavior": "exclusive",
    "tenant_find_fee": 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. Can be building.
• created timestamp

  Time at which the object was created. Measured in seconds since the Unix epoch.
• accounting_code string

  The accounting code to be used with invoice items associated with this building.
• active boolean

  Whether the building is currently available for use.
• address integer

  The building's address.
• currency string

  Three-letter ISO currency code, in lowercase. Must be a supported currency.
• description string

  An arbitrary string attached to the object. Often useful for displaying to users.
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• name string

  The building's name.
• single_unit boolean

  Whether the building can only have a single unit.
• type string

  The building's type. Can be block_management, commercial, residential or student.
• unit_fees object

  unit_fees.management_fee float

  The default management fee to apply to units. Maximum decimal precision of 2.

  unit_fees.management_fee_amount integer

  The default management fee fixed amount, represented as a whole integer in the smallest currency unit.

  unit_fees.management_fee_type string

  The management fee type. Can be percentage or fixed.

  unit_fees.renewal_fee integer

  The default renewal fee to apply to units, represented as a whole integer in the smallest currency unit.

  unit_fees.tax float

  The default tax to apply to units. Maximum decimal precision of 2.

  unit_fees.tax_behavior string

  The default tax behavior to apply to units. One of exclusive or inclusive. Can be exclusive or inclusive.

  unit_fees.tenant_find_fee integer

  The default tenant find fee to apply to units, represented as a whole integer in the smallest currency unit.

Create a building

POST /v1/buildings

curl https://api.yorlet.com/v1/buildings \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "build_test",
  "object": "building",
  "created": 1627210800,
  "accounting_code": null,
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "name": null,
  "single_unit": false,
  "type": null,
  "unit_fees": {
    "management_fee": null,
    "management_fee_amount": null,
    "management_fee_type": "percentage",
    "renewal_fee": null,
    "tax": null,
    "tax_behavior": "exclusive",
    "tenant_find_fee": null
  }
}

Creates a new building.

Parameters

• address required  object

  The building's address.

  address.country required  string

  Two-letter country code (ISO 3166-1 alpha-2).

  address.line1 required  string

  Address line 1 (e.g., street, PO Box, or company name).

  address.city string

  City, district, suburb, town, or village.

  address.line2 string

  Address line 2 (e.g., apartment, suite, unit, or building).

  address.postal_code string

  Postal code.

  address.state string

  State, county, province, or region.
• name required  string

  The building's name.
• accounting_code string
• active boolean
• currency string

  The default currency for the building and any units associated with the building. Can be eur, gbp, sek or usd.
• description string
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• single_unit boolean
• type string

  Can be block_management, commercial, residential or student.
• unit_fees object

  unit_fees.management_fee number

  The unit's management fee percentage amount.

  unit_fees.management_fee_amount integer

  The unit's management fee fixed amount.

  unit_fees.management_fee_type string

  Can be percentage or fixed.

  unit_fees.renewal_fee integer

  The unit's renewal fee.

  unit_fees.tax number

  The tax to apply to the unit fees.

  unit_fees.tax_behavior string

  Whether the tax is included or excluded from the fees. Can be inclusive or exclusive.

  unit_fees.tenant_find_fee integer

  The unit's tenant find fee.

Returns

Returns the building object if the request succeeded.

Retrieve a building

GET /v1/buildings/:id

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

Example Response

{
  "id": "build_test",
  "object": "building",
  "created": 1627210800,
  "accounting_code": null,
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "name": null,
  "single_unit": false,
  "type": null,
  "unit_fees": {
    "management_fee": null,
    "management_fee_amount": null,
    "management_fee_type": "percentage",
    "renewal_fee": null,
    "tax": null,
    "tax_behavior": "exclusive",
    "tenant_find_fee": null
  }
}

Retrieves the building with the given ID.

Parameters

• No parameters

Returns

Returns a building object if a valid identifier was provided.

Update a building

POST /v1/buildings/:id

curl https://api.yorlet.com/v1/buildings/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "build_test",
  "object": "building",
  "created": 1627210800,
  "accounting_code": null,
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "name": null,
  "single_unit": false,
  "type": null,
  "unit_fees": {
    "management_fee": null,
    "management_fee_amount": null,
    "management_fee_type": "percentage",
    "renewal_fee": null,
    "tax": null,
    "tax_behavior": "exclusive",
    "tenant_find_fee": null
  }
}

Updates the specified building by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

• accounting_code string
• active boolean
• address object

  The building's address.

  address.country required  string

  Two-letter country code (ISO 3166-1 alpha-2).

  address.line1 required  string

  Address line 1 (e.g., street, PO Box, or company name).

  address.city string

  City, district, suburb, town, or village.

  address.line2 string

  Address line 2 (e.g., apartment, suite, unit, or building).

  address.postal_code string

  Postal code.

  address.state string

  State, county, province, or region.
• description string
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• name string

  The building's name.
• type string

  Can be block_management, commercial, residential or student.
• unit_fees object

  unit_fees.management_fee number

  The unit's management fee percentage amount.

  unit_fees.management_fee_amount integer

  The unit's management fee fixed amount.

  unit_fees.management_fee_type string

  Can be percentage or fixed.

  unit_fees.renewal_fee integer

  The unit's renewal fee.

  unit_fees.tax number

  The tax to apply to the unit fees.

  unit_fees.tax_behavior string

  Whether the tax is included or excluded from the fees. Can be inclusive or exclusive.

  unit_fees.tenant_find_fee integer

  The unit's tenant find fee.

Returns

Returns the building object if the update succeeded.

Delete a building

DELETE /v1/buildings/:id

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

Example Response

{
  "id": "build_test",
  "object": "building",
  "deleted": true
}

Permanently deletes a buidling. This cannot be undone.

Parameters

• No parameters

Returns

Returns an object with a deleted parameter on success. If the building ID does not exist, this call throws an error.

List all buildings

GET /v1/buildings

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "build_test",
      "object": "building",
      "created": 1627210800,
      "accounting_code": null,
      "currency": "gbp",
      "description": null,
      "metadata": {},
      "name": null,
      "single_unit": false,
      "type": null,
      "unit_fees": {
        "management_fee": null,
        "management_fee_amount": null,
        "management_fee_type": "percentage",
        "renewal_fee": null,
        "tax": null,
        "tax_behavior": "exclusive",
        "tenant_find_fee": null
      }
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of buildings. The buildings are returned sorted by creation date, with the most recent buildings appearing first.

Parameters

• active boolean

  Whether to return active buildings.
• ids array of strings

  The IDs of the buildings to return.

Returns

A object with a data property that contains an array of buildings.

Contract Templates

Endpoints

POST    /v1/contract_templates
GET     /v1/contract_templates/:id
POST    /v1/contract_templates/:id
DELETE  /v1/contract_templates/:id
GET     /v1/contract_templates

Contract template objects allow you to manage document templates for different types of contracts. The API allows you to create, delete, and update your templates. You can retrieve individual templates as well as a list of all your templates.

The contract template object

The contract template object

{
  "id": "ct_test",
  "object": "contract_template",
  "created": 1627210800,
  "custom_title": null,
  "file": "file_test",
  "file_version": "v1",
  "name": "Default AST",
  "type": "ast"
}

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. Can be contract_template.
• created timestamp

  Time at which the object was created. Measured in seconds since the Unix epoch.
• custom_title string

  The custom title for the contract template.
• created_by string

  ID of the user that created the contract template.
• file string

  The file for the contract template.
• file_version string

  The version of the file for the contract template.
• name string

  The name of the contract template.
• type string

  The type of the contract template.
• versions array

  The versions of the contract template.

Create a contract template

POST /v1/contract_templates

curl https://api.yorlet.com/v1/contract_templates \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ct_test",
  "object": "contract_template",
  "created": 1627210800,
  "custom_title": null,
  "file": "file_test",
  "file_version": "v1",
  "name": "Default AST",
  "type": "ast"
}

Creates a new contract template.

Parameters

• file required  string

  The file for the contract template.
• name required  string

  The name of the contract template.
• type required  string

  The type of the contract template. Can be addendum, ast, ast_agent, custom, guarantor, licence or property_management_agreement.
• custom_title string

  The custom title for the contract template.
• default boolean

  Whether the contract template is the default template for the account.

Returns

Returns the contract template object if the request succeeded.

Retrieve a contract template

GET /v1/contract_templates/:id

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

Example Response

{
  "id": "ct_test",
  "object": "contract_template",
  "created": 1627210800,
  "custom_title": null,
  "file": "file_test",
  "file_version": "v1",
  "name": "Default AST",
  "type": "ast"
}

Retrieves the contract template with the given ID.

Parameters

• No parameters

Returns

Returns a contract template object if a valid identifier was provided.

Update a contract template

POST /v1/contract_templates/:id

curl https://api.yorlet.com/v1/contract_templates/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ct_test",
  "object": "contract_template",
  "created": 1627210800,
  "custom_title": null,
  "file": "file_test",
  "file_version": "v1",
  "name": "Default AST",
  "type": "ast"
}

Updates the specified contract template by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

• name required  string

  The name of the contract template.

Returns

Returns the contract template object if the update succeeded.

Delete a contract template

DELETE /v1/contract_templates/:id

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

Example Response

{
  "id": "ct_test",
  "object": "contract_template",
  "deleted": true
}

Permanently deletes a contract template. This cannot be undone.

Parameters

• No parameters

Returns

Returns an object with a deleted parameter on success. If the template ID does not exist, this call throws an error.

List all contract templates

GET /v1/contract_templates

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ct_test",
      "object": "contract_template",
      "created": 1627210800,
      "custom_title": null,
      "file": "file_test",
      "file_version": "v1",
      "name": "Default AST",
      "type": "ast"
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of contract templates. The templates are returned sorted by creation date, with the most recent templates appearing first.

Parameters

• type string

  The type of the contract template. Can be addendum, ast, ast_agent, custom, guarantor, licence or property_management_agreement.

Returns

A object with a data property that contains an array of contract templates.

Customers

Endpoints

POST    /v1/customers
GET     /v1/customers/:id
POST    /v1/customers/:id
DELETE  /v1/customers/:id
GET     /v1/customers

Customer objects allow you to create applications, accept payments and manage subscriptions. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers.

The customer object

The customer object

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

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. Can be customer.
• created timestamp

  Time at which the object was created. Measured in seconds since the Unix epoch.
• address object

  The customer’s address.
• archived boolean

  Whether the customer is archived. An archived customer cannot have applications, invoices, subscriptions, or payments create against them.
• default_payment_method stringexpandable

  ID of the default payment method for the customer.
• delinquent boolean

  A boolean to indicate whether the customer has any outstanding invoices.
• description string

  An arbitrary string attached to the object. Often useful for displaying to users.
• email string

  The customer’s email address.
• invoice_prefix string

  The prefix for the customer used to generate unique invoice numbers.
• metadata string

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• invoicing object

  The customer’s invoicing settings.

  invoicing.email_to string

  The email address to send invoices to.

  invoicing.email_cc array

  List of emails to CC in the invoice email.
• next_invoice_sequence string

  The suffix of the customer’s next invoice number, e.g., 0001.
• legal_completed boolean

  Whether the customer's legal information is completed.
• legal object

  The customer's legal information.
• name string

  The customer's name.
• phone string

  The customer's phone number.
• resident boolean

  Whether the customer is currently an active resident.

Create a customer

POST /v1/customers

curl https://api.yorlet.com/v1/customers \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "email": "[email protected]"
}'

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

Creates a new customer.

Parameters

• email required  string

  The customer's email address.
• address object

  The customer's address.

  address.country required  string

  Two-letter country code (ISO 3166-1 alpha-2).

  address.line1 required  string

  Address line 1 (e.g., street, PO Box, or company name).

  address.city string

  City, district, suburb, town, or village.

  address.line2 string

  Address line 2 (e.g., apartment, suite, unit, or building).

  address.postal_code string

  Postal code.

  address.state string

  State, county, province, or region.
• description string

  An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
• invoice_prefix string

  The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.
• invoicing object

  The customer’s invoicing settings.

  invoicing.arrears_emails boolean

  Whether to send arrears emails to the customer.

  invoicing.email_cc array of strings

  List of emails to CC in the invoice email.

  invoicing.email_to string

  The email address to send invoices to.
• legal object

  The customer's legal information. Used for generating contracts.

  legal.dob object

  legal.dob.day required  integer

  legal.dob.month required  integer

  legal.dob.year required  integer

  legal.first_name string

  The customer's full legal firstname.

  legal.last_name string

  The customer's full legal lastname.

  legal.previous_addresses array of objects

  The customer's previous addresses.

  legal.previous_addresses.country required  string

  Two-letter country code (ISO 3166-1 alpha-2).

  legal.previous_addresses.line1 required  string

  Address line 1 (e.g., street, PO Box, or company name).

  legal.previous_addresses.city string

  City, district, suburb, town, or village.

  legal.previous_addresses.line2 string

  Address line 2 (e.g., apartment, suite, unit, or building).

  legal.previous_addresses.postal_code string

  Postal code.

  legal.previous_addresses.state string

  State, county, province, or region.
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• name string

  The customer's name.
• next_invoice_sequence integer

  The sequence to be used on the customer’s next invoice. Defaults to 1.
• phone string

  The customer's phone number.

Returns

Returns the customer object if the request succeeded.

Retrieve a customer

GET /v1/customers/:id

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

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

Retrieves the customer with the given ID.

Parameters

• No parameters

Returns

Returns a customer object if a valid identifier was provided.

Update a customer

POST /v1/customers/:id

curl https://api.yorlet.com/v1/customers/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

• address object

  The customer's address.

  address.country required  string

  Two-letter country code (ISO 3166-1 alpha-2).

  address.line1 required  string

  Address line 1 (e.g., street, PO Box, or company name).

  address.city string

  City, district, suburb, town, or village.

  address.line2 string

  Address line 2 (e.g., apartment, suite, unit, or building).

  address.postal_code string

  Postal code.

  address.state string

  State, county, province, or region.
• archived boolean
• description string

  An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
• email string

  The customer's email address.
• invoice_prefix string

  The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.
• invoicing object

  The customer’s invoicing settings.

  invoicing.arrears_emails boolean

  Whether to send arrears emails to the customer.

  invoicing.email_cc array of strings

  List of emails to CC in the invoice email.

  invoicing.email_to string

  The email address to send invoices to.
• legal object

  The customer's legal information. Used for generating contracts.

  legal.dob object

  legal.dob.day required  integer

  legal.dob.month required  integer

  legal.dob.year required  integer

  legal.first_name string

  The customer's full legal firstname.

  legal.last_name string

  The customer's full legal lastname.

  legal.previous_addresses array of objects

  The customer's previous addresses.

  legal.previous_addresses.country required  string

  Two-letter country code (ISO 3166-1 alpha-2).

  legal.previous_addresses.line1 required  string

  Address line 1 (e.g., street, PO Box, or company name).

  legal.previous_addresses.city string

  City, district, suburb, town, or village.

  legal.previous_addresses.line2 string

  Address line 2 (e.g., apartment, suite, unit, or building).

  legal.previous_addresses.postal_code string

  Postal code.

  legal.previous_addresses.state string

  State, county, province, or region.
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• name string

  The customer's name.
• next_invoice_sequence integer

  The sequence to be used on the customer’s next invoice. Defaults to 1.
• phone string

  The customer's phone number.

Returns

Returns the customer object if the update succeeded.

Delete a customer

DELETE /v1/customers/:id

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

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "deleted": true
}

Permanently deletes a customer. This cannot be undone.

Parameters

• No parameters

Returns

Returns an object with a deleted parameter on success. If the customer ID does not exist, this call throws an error.

List all customers

GET /v1/customers

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "cus_test",
      "object": "customer",
      "created": 1627210800,
      "archived": false,
      "default_payment_method": null,
      "delinquent": false,
      "description": null,
      "email": "[email protected]",
      "invoice_prefix": null,
      "metadata": {},
      "invoicing": {
        "arrears_emails": true,
        "email_to": null,
        "email_cc": []
      },
      "next_invoice_sequence": 1,
      "legal_completed": false,
      "legal": {},
      "name": "Jane Doe",
      "resident": false
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

Parameters

• active_tenancy string

  The ID of the active tenancy to filter results.
• archived boolean

  Whether to return archived customers.
• delinquent boolean

  Whether to return delinquent customers.
• email string

  A case-sensitive filter on the list based on the customer’s email field. The value must be a string.
• resident boolean

  Whether to return resident customers.
• risk_level string or array of strings

  The risk level to filter results. Can be one or many of elevated or highest.
• type string

  The type of customer to filter results.

Returns

A object with a data property that contains an array of customers.

Deposits

Endpoints

POST    /v1/deposits
GET     /v1/deposits/:id
POST    /v1/deposits/:id
POST    /v1/deposits/:id/activate
POST    /v1/deposits/:id/return
POST    /v1/deposits/:id/mark_returned
POST    /v1/deposits/:id/transfer
DELETE  /v1/deposits/:id
GET     /v1/deposits

The deposit object

The deposit object

{
  "id": "deposit_test",
  "object": "deposit",
  "created": 1627210800,
  "amount": 100000,
  "amount_charged": 0,
  "amount_returned": 0,
  "application": null,
  "automatic_deposit": {
    "branch_id": null,
    "enabled": false,
    "last_error": null,
    "status": null
  },
  "country": null,
  "currency": "gbp",
  "handled_externally": false,
  "metadata": {},
  "requires_external_transfer": false,
  "requirements": {},
  "returned_at": null,
  "returned": false,
  "scheme": {
    "certificate": null,
    "provider": null,
    "registration_deadline": null,
    "registration_number": null,
    "type": null
  },
  "status": null,
  "transferred": false,
  "unit": 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. Can be deposit.
• created timestamp

  Time at which the object was created. Measured in seconds since the Unix epoch.
• amount integer

  The deposit amount.
• amount_charged integer

  The amount charged for the deposit.
• amount_returned integer

  The amount returned for the deposit.
• application stringexpandable

  The identifier of the application for the deposit.
• automatic_deposit object

  The automatic deposit settings for this deposit.
• country string

  The country of the deposit.
• currency string

  Three-letter ISO currency code, in lowercase. Must be a supported currency.
• customer_ids array

  Array of customer IDs this deposit is for.
• description string

  The description of the deposit.
• handled_externally boolean

  Whether the deposit is handled externally.
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• requires_external_transfer boolean

  Whether the deposit requires transfer to an external scheme.
• requirements object

  The requirements for the deposit.
• returned_at timestamp

  The date the deposit was returned.
• returned boolean

  Whether the deposit has been returned.
• scheme object

  A hash containing details of the deposit scheme.
• source_transactions object

  The source transactions for the deposit.
• status string

  The status of the deposit.
• transferred boolean

  Whether the deposit has been transferred.
• unit stringexpandable

  ID of the unit associated with this deposit.

Create a deposit

POST /v1/deposits

curl https://api.yorlet.com/v1/deposits \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "deposit_test",
  "object": "deposit",
  "created": 1627210800,
  "amount": 100000,
  "amount_charged": 0,
  "amount_returned": 0,
  "application": null,
  "automatic_deposit": {
    "branch_id": null,
    "enabled": false,
    "last_error": null,
    "status": null
  },
  "country": null,
  "currency": "gbp",
  "handled_externally": false,
  "metadata": {},
  "requires_external_transfer": false,
  "requirements": {},
  "returned_at": null,
  "returned": false,
  "scheme": {
    "certificate": null,
    "provider": null,
    "registration_deadline": null,
    "registration_number": null,
    "type": null
  },
  "status": null,
  "transferred": false,
  "unit": null
}

Creates a new deposit.

Parameters

• application required  string

  The ID of the application this deposit is for.
• amount integer

  The amount of the deposit.
• automatic_deposit object

  A hash containing details of the automatic deposit.

  automatic_deposit.enabled required  boolean

  Whether to automatically deposit the funds.

  automatic_deposit.branch_id string

  The ID of the branch to automatically deposit the funds to.
• country string

  The ISO 3166-1 alpha-2 country code of the deposit.
• description string

  An arbitrary string attached to the object. Often useful for displaying to users.
• handled_externally boolean

  Whether the deposit is handled externally or not. Usually this means the landlord or a thrid party has registered the deposit and will handle it.
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• scheme object

  A hash containing details of the deposit scheme.

  scheme.certificate string

  The certificate ID of the deposit scheme.

  scheme.provider string

  The provider of the deposit scheme. Can be dps, mydeposits or tds.

  scheme.registration_number string

  The registration number of the deposit scheme.

  scheme.type string

  The type of deposit scheme. Can be custodial or insured.

Returns

Returns the Deposit object if the request succeeded.

Retrieve a deposit

GET /v1/deposits/:id

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

Example Response

{
  "id": "deposit_test",
  "object": "deposit",
  "created": 1627210800,
  "amount": 100000,
  "amount_charged": 0,
  "amount_returned": 0,
  "application": null,
  "automatic_deposit": {
    "branch_id": null,
    "enabled": false,
    "last_error": null,
    "status": null
  },
  "country": null,
  "currency": "gbp",
  "handled_externally": false,
  "metadata": {},
  "requires_external_transfer": false,
  "requirements": {},
  "returned_at": null,
  "returned": false,
  "scheme": {
    "certificate": null,
    "provider": null,
    "registration_deadline": null,
    "registration_number": null,
    "type": null
  },
  "status": null,
  "transferred": false,
  "unit": null
}

Retrieves the deposit with the given ID.

Parameters

• No parameters

Returns

A Deposit object if a valid identifier was provided.

Update a deposit

POST /v1/deposits/:id

curl https://api.yorlet.com/v1/deposits/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "deposit_test",
  "object": "deposit",
  "created": 1627210800,
  "amount": 100000,
  "amount_charged": 0,
  "amount_returned": 0,
  "application": null,
  "automatic_deposit": {
    "branch_id": null,
    "enabled": false,
    "last_error": null,
    "status": null
  },
  "country": null,
  "currency": "gbp",
  "handled_externally": false,
  "metadata": {},
  "requires_external_transfer": false,
  "requirements": {},
  "returned_at": null,
  "returned": false,
  "scheme": {
    "certificate": null,
    "provider": null,
    "registration_deadline": null,
    "registration_number": null,
    "type": null
  },
  "status": null,
  "transferred": false,
  "unit": null
}

Updates the deposit with the given ID.

Parameters

• amount integer

  The amount of the deposit.
• description string

  An arbitrary string attached to the object. Often useful for displaying to users.
• handled_externally boolean

  Whether the deposit is handled externally or not. Usually this means the landlord or a thrid party has registered the deposit and will handle it.
• metadata object

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
• scheme object

  A hash containing details of the deposit scheme.

  scheme.certificate string

  The certificate ID of the deposit scheme.

  scheme.provider string

  The provider of the deposit scheme. Can be dps, mydeposits or tds.

  scheme.registration_number string

  The registration number of the deposit scheme.

  scheme.type string

  The type of deposit scheme. Can be custodial or insured.